Barker Chapter 12
This chapter is mostly a series of tidbits advising you how to write certain topics.
1) Write about Actions rather than Functions.
Tell the reader what they can do with a tool, rather than describe the tool itself.
Bad:
Hyperlink: Inserts a hyperlink or edits the selected hyperlink.
Good:
Hyperlink: This button allows you to link selected text to other text or documents or edit the properties of selected hyperlinks.
2) Revise for the Active Voice
The active voice puts a subject at the beginning of each sentence, a verb in the middle, and a receiver of the action at the end.
Bad:
The file menu is used to…
Good:
You can use the file menu to…
3) Revise to keep Writing Simple
Break down complex sentences in order to enhance the reader’s ability to understand your meaning the first time they read it.
Try to be a little repetitive in your writing; it helps the readers mind organize steps, for instance, when they all begin with an action verb.
5) Add Operational Overviews
Use a paragraph to give a conceptual overview of the steps before listing the steps.
6) Make sure topic matches Heading
If your heading states something general, don’t get overly specific.
Often when writing, the writers tone takes on the feeling or a robot or telegraph. Try to sound slightly conversational, even in a business setting, to keep the user engaged.
8) Use Humor with Caution
There’s a lot of opportunity for humor to fall flat. Never use it in reference sections, seldom use it in procedures, occasionally in tutorials or background information.
posted by Lilith Singer | 7:37 AM
7 Comments:
I might argue a little with #2 - Revise for the Active Voice. I don't disagree that we should write in an active voice. I disagree with the part about beginning with a subject. I'd like to suggest a "better" example for online documentation:
Bad:
The file menu is used to…
Good:
You can use the file menu to…
Better: Use the File menu to...
Start with an action verb and get rid of the "You can" to keep it more simple and active.
There is always a fine line when writing instructions, you need to be specific enough to get the point across, but concise enough that said point can be determined. A catch-22 if you will.
Finally, a chapter dealing with the art of writing.
It is important to use the active voice. I also like the suggestion to get the subject as near as possible to the front of the sentence. It makes it easier for the reader to grasp the concept of the sentence.
Finally, I also agree about the use of humor. We should be straight-forward in our writing and not attempt to be "cute" when writing in this context.
I think what Anne is refering to is the "imperative mood." Write procedures in a manner that sounds like you are giving a direct command to the reader (like this sentence, for instance). As long as you don't use a level of diction that makes you look stuffy or harsh, the reader will have no problem following orders. This will help the reader keep their minds focused on what task they must complete next, and they'll feel confident they are recieving solid directions.
I think there are a lot of guidelines Barker could have added to this list, but he does include some essential information. What is important to remember is that these guidelines are not rules; they will not always apply to every situation. By writing these guidelines, Barker is saying "well, these things usually work." You should generally stick to them, but always look to the rhetorical situation to guide your decisions.
I feel like this chapter contradicts what I have generally learned about writing. I have always been told to leave 'you' out of it. I think it makes perfect sense and his arguments for doing so are logical. I guess it comes down to who/what you are writing for.
I’ve always struggled with the active tone of voice! I’m not sure if it’s because of my struggles with the technical side of grammar, but it is one area that has always been difficult for me to understand. I’ll get papers back with corrections on how to use the active voice, but I never seem to fully grasp that concept. Perhaps it’s a learning experience that will be ongoing?
I agree that humor can be difficult to use in tech comm. The odds are high that it can sound cheesy or tacky and just distract. However, the suicide Help in Barker was just great! I’m going to have that framed someday.
I agree with you Anne. It is a bit akward to assume one can always use the subject at the beginning. It is more of a command and the user has no confusion as to what he/she should do. It is so important to break down sentences. The more words per sentence the higher the readability is. I think the recommended words per sentence is 16.
Post a Comment
<< Home