Next, Barker provides a list of guidelines for ensuring that your style is oriented to users’ needs.
Write About Actions Rather Than Functions
Instead of simply giving a definition of the function, you should answer the question of “Why would I want to perform this function?” If you identify the object and tell the read what to do with the object, you are creating a set of tools to help the user do their work.
Revise for the Active Voice
Passive voice makes a passage seem impersonal, which will make the reader feel manipulated uncaringly. Active voice is more personal and direct, which makes the reader feel empowered.
Revise to Keep Writing Simple
You don’t want your reader to waste time rereading sentences, so try to make passages simple. Simplicity helps every aspect of software manual writing and you should strive for simplicity in each sentence.
Revise to Build Parallel Structures
Parallel items acknowledge the similarities between concepts and express that similarity in matching grammatical structures. This is one of the best solutions to the problem of using the user’s short-term memory effectively by helping readers remember even though they may not recognize the pattern.
Add Operational Overviews
Because users often read for meaning, you should provide prose passages containing clear overviews of concepts as well as straight procedures; users appreciated learning the conceptual model of the program and how the program does its processing (389).
Barker then begins a discussion about language, learning, and how to effectively present information in software documentation.
How Do We Process Language?
Barker writes that to set goals of language use to support task orientation, you must first look at how readers process language. He notes that the act of reading requires that the concept in the reader’s mind bond with words on the page and that the words register as significant, which is meaning. The words don’t convey meaning to the reader, but the reader brings meaning to the words. The more clearly writers can anticipate that task the more task-oriented the manual.
Performance-Oriented Language
Performance oriented software documentation is when there are clear explanations of how to perform using the software. Using the active voice, using the ‘you’ pronoun, and using the imperative verb add to the performance orientation of the style. You should write to an actual human being, which will make the documentation less stuffy, formal and robot-like.
How Do We Remember and Learn?
After finding the right answer, users must remember the idea until they get back to work. This means that the writer must rely on both short and long-term memory. You should strive for a style of writing that has words that connect to the users’ mind, which will make it easier to remember. To do this, you must structure the sentences carefully using the following sentences: patterned, highly parallel, balanced, and sentences that end in three rhythmic clauses.
Style Problems in Software Documentation
Barker writes that problems with style in software documentation relate directly to your overall goal of making software easy to use. He then provides some of the problems associated with writing in software documentation.
- Acronyms: Users can often understand common acronyms such as DOS and RAM, but the difficulty comes when some of the terms constructed as part of the computer program or system appear in the document. You can’t always avoid acronyms and abbreviations, but try to use a few of them in a sentence at a time.
- Synonyms: You should use these consistently and accurately as to not confuse the user. You should also try to use the terms that users will most likely recognize and build in crossover techniques, such as synonyms in parentheses.
- Paragraphs and Sentences Too Long: Paragraphs should focus on explanations, not performance, and not on steps telling the reader what to do. It is best if the writer can forget about paragraphs and just think in terms of lists and chunks of no more than three sentences.
- Emphasizing the Computer Instead of the Program: A writer must remember that a computer doesn’t perform tasks, the program does. When writing software documentation, you must think about the program performing the functions, which will also help promote the program.
- No Connection between the Heading and the Topic: Often, in a manual, headings are following by paragraphs explaining a program. However, the information in these passages doesn’t always match the heading. Instead, the writer has included one or two relevant details about the program, which get presented in a highly technical language.
- Too Formal Tone: Software documentation is intended for real people, so it shouldn’t be too formal. According to Barker, speaking in a informal tone—without being overly familiar or presumptuous—makes contact more quickly and evokes the user’s desire to do well on the job. You can incorporate an informal tone into your writing by using the following characteristics: use of contractions, reference to other users, and humorous aside.
- When to Use Humor: Barker writes that humor sparks as much controversy as it does good feeling in manual writing. Bad humor can cause a user to reject a manual. Common sense tells us that humor will not work in all kinds of documentation, especially sections where the user simply looks up information. You should always test humor before the final draft.
- Ambiguous Task Names: In task-oriented documentation you should name tasks clearly, with a sense of planning for the user’s new vocabulary. Don’t fall into the tendency of referring to tasks vaguely because this leaves the user with more questions.
- Step Not a Step: The step constitutes the basic element of human-computer interaction, so you should make sure that each step is actually a step and not just a guide or information about the previous/next step.
- Omitted Articles: Barker ends the chapter by discussing the tendency for software documentation to fall into the telegram style of writing. We don’t have to pay for words anymore, and such attempts to leave out articles to sound official fall flat. Since you are communicating with real people, you should use real language.
