An important method in writing software manuals is to do so in a way that is performance-oriented.
Guidelines
There are five guidelines Barker writes about regarding user-oriented style:
- Write about actions rather than functions.
Structure the language to support the resulting actions of functions. Identify the function and then explain what the user can do with it. The more you focus on usefulness rather than on functions, the more the user will realize that usefulness. - Revise for the active voice.
Revise statements to include active voice. See Table 12.1 on page 386 for examples. - Revise to keep writing simple
Simplicity helps every aspect of manual writing. Avoid extra filler and similar unnecessary information. Keep the subject and verb together. - Revise to build parallel structures
Consider parallelism (for example, consistently using the same grammatical structure such as verb ending ing in headings) as consistency keeps a document's content from becoming confusing. Check Table 12.2 on page 388 for examples. - Add operational overviews
Providing overviews cuts down on confusion for users who may not be completely familiar with the material. Tell them how the program benefits them. "Your manual is like a bathroom key: People want to get their hands on it not because of its intrinsic properties but because it lets them do what they need to do" (389). Writers primarily use three ways to emphasize explanations of abstract concepts: "the theoretical (emphasizing the theories behind the working of the program), the technical (emphasizing the technical functioning of the program), and the operational (empasizing the application of the program)" (389). Check Table 12.3 on page 390 for more details.
Discussion
"In software documentation, you will often use different writing styles and different tones to support different user tasks" (390). So,
How Do We Process Language?
First, you need to write words in a way that connects with the user. Information needs to be significant to them.
Users have specific searching behavior or problem-solving strategies, so the document information should appropriate the energy the user puts into specific tasks. The amount of meaning a text has depends on the user's task.
Performance-Oriented Language
Slow read-through rarely pays off. To avoid this problem, the software manual writer should use
- active voice.
- the pronoun you to make the text interactive.
- imperative verbs to trigger actions.
- real language (language that the reader can actually understand and learn from rather than formal language).
How Do We Remember and Learn
Users need to remember ideas they read in order to learn. Try to make connections with the user's memory; this will trigger those memories and will make learning easier.
Structured Sentences
Thorough knowledge of how to structure information clearly in sentences is essential for retention. Sentences should be simple and short.
Style Problems in Software Documentation
Styles issues such as too many abstractions, little performance support, and overly complex syntax will make your information difficult to use (See Table 12.4 on page 393 for more details).
Acronyms
Acronyms can make complex systems easier to define; however, overusing them is not recommended. They will show up, though as software systems often contain hundreds of them. They also can save a lot of time.
Synonyms
Synonyms should be used consistently but carefully as they may be similar, but can evoke different meanings. One option to consider regarding this is indexing.
Paragraphs and Sentences Too Long
Paragraphs should focus on explanations, not performance, and not on steps telling the reader what to do. They work best when they support a simple concept. "They help explain what happens after a step, and, because the user will not usually tackle paragraphs unless he or she must, they shuld read as quickly and easily as possible" (395).
Emphasizing the Computer Instead of the Program
Since the user interacts with the program rather than the computer, you should create information that focuses on working with the software.
No Connection Between the Heading and the Topic
Headings must be meaningful, and the topic following should support that information. Specific explanations are usually all that's needed.
Too Formal Tone
Make software documentation conversational, not too formal. Sentences are meant to connect with another real person. Speaking in an informal tone makes contact more quickly and evokes the user's desire to do well on the job.
When to Use Humor
Avoid it. That's the impression I got from the reading.
Ambiguous Task Names
Avoid making vague references. "In task-oriented documentation you should name tasks clearly, with a sense of planning for the user's new vocabulary" (398). The name of the task should appear frequently in the text of the manual.
Step Not a Step
Examine youre steps to make sure they contain a clearly stated action, often using an imperative verb.
Thanks! Team 3 (Carlson and Hood)
12 comments:
I feel as if a lot of the material covered in this chapter is a review of what I learned in Editing Tech. Publications last semester. It is useful information, but just a review for me.
Very nice summary. I thought it was all very common sense material, but it was a nice refresher. Thank you.
I'd agree with the other comments about this being a general review. A number of the tips sum up a lot of what we've already learned this semester, if not in past English classes. I'm curious about using humor in task-based writing. Certainly, with some topics, it may not be appropriate. But I wonder if it would be appropriate in a few contexts, especially since Barker recommends keeping language simple and informal. I can't think of specific examples, but I think there is a place for humorous procedures.
Task oriented and user centered - that really sums up the chapter for me. If a writer can keep the user focused on a step-by-step process with clear writing and minimal distraction, then a document will be effective. I really didn't find anything I disagreed with in this chapter, as the others have said, it is a lot of common sense material, but useful nonetheless.
One major issue I run into in engineering is the use of passive voice. Since it sounds so uncommittal when it comes to deadlines and deliverables, passive voice is preferred in engineering reports.
For me, this was one of the most important chapters in the book. You don't really know if you're writing good documentation until you're sure that you've got the language right. This is baseline stuff, but it's absolutely essential to the success your documentation. I like the idea of trying to write like you're speaking to real people--that's something that I have to keep in my mind because it doesn't always come naturally to me.
Good quote about the bathroom key. That is a great comparison. The bottom line is really about getting the work done without interference or roadblocks. When you are in the middle of a project and you run into a problem, you simply want to find the solution in the shortest, simplest, most understandable way possible. Like Lance said, "Task oriented and user centered.
I guess I am not surprised to see that the tips for well written software documentation are the same for good business writing. Active voice, first or second person, conversational tones, etc. Yes, some softwared manuals can actually be mildly interesting and engaging.
Barker makes an interesting point when he talks about learning. I've read a number of papers on the way new information builds on our framework of preexisting knowledge. As writers, we have to remember to define new concepts and link them to other well-known or previously defined concepts so the reader will be able to understand and remember. We have to present information in the proper context for it to make sense.
I sometimes struggle with the language to be what this chapter calls: simple, in active voice and conversational tone. All the tips in this chapter are useful for me. I have noticed the improvement in my writing and language use since I have started the program. I think I will have to reread this chapter when I begin to write more in the field of technical communication to produce clear and concise documents.
Although most of the information in this chapter was review from the technical editing class and reiterated some of what Campbell emphasized, I did appreciate the discussion of common problems encountered in manuals. I also thought the discussion of how we process and remember information was not only interesting, but useful.
I earned my undergraduate degrees in psychology and English. When I had to write research reports in psychology, I always tended to use passive voice to make the writing seem more formal. When I first came to technical communication, it felt like I was breaking all the rules because I could use “you” and first person. It is interesting (as Vanda commented) the different styles different disciplines used-not to say that all psychology reports used passive voice-but I rarely used “I.” More so-“the researcher.” I like this type of writing though because it is effective and speaks to the audience.
Post a Comment