Michael J. Albers wrote an article about good software documentation and the techniques to create them.
“To successfully communicate to users, documentation must do more than meet the user’s information needs, it must present the information in the same way the user processes the information. We can change appearances, but effective communication does not lie in appearances. Communication works at the level of assumptions, implications, and expectations. Effective communication means determining and providing answers to the complex problems of the real-world. Analysis should be stated “in terms of the behavior-shaping goals and constraints that define the boundaries of a space guided by their local and subjective performance criteria” (11). Dobin insists that to support problem solving for open-ended problems we must gain an in-depth understanding of the user and not the software. “The user’s vocabulary, the user’s reasons for looking things up, and the problems the user confronts must be clearly anticipated’ (3, p.89). Actually, if we define the conditions and real workplace tasks early in the project and then use that information to design an interface meeting the user’s needs, the job of the technical communicator becomes much easier.
We no longer must fix a poor interface with documentation. Instead, we are create documentation the helps the user solve real-world problems by putting the right information in the right place at the right time in the right format. To put this in different terms: give users exactly what they need, when they need it-no more, no less.
(…)
We must go beyond simple procedures and create documents which assist in solving complex problems.”
related links
The Key for Effective Documentation: Answer the User’s Real Question
