This is just a comment on Barker's chapter 11, not the initial blog!
The concepts Barker writes about seem to follow the guidelines for all writing such as using active voice, keeping writing simple and geared to the user, and using the parallel structure. I thought he nailed it exactly with the idea that "A 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." Perfect. I look for exactly this in any manual. I want the information I need and the rest can wait until later, or never.
I learned about explaining abstract concepts when writing and, at my job, I usually use the operational concept that simply tells me what I need to know. I think AuthorIt might fall into the technical functioning of a program and that may be where I'm experiencing difficulties because I'm required to understand the technical aspects in order to perform what I need to do for the documentation project. I'm more interested in the productivity of AuthorIt than learning the technical parts. And that might be where the sticky part lies.
Understanding the different types of parallelism helps with all tutorial and instruction writing. Parallelism seems to work well in tutorials because it's based on action by the user and that is what our documentation and usability projects require in the quest to be user friendly and user helpful.
Subscribe to:
Post Comments (Atom)
7 comments:
I agree with Joan's assessment of the chapter. Especially when in a time crunch, "just tell me what I need to know to get the work done" is a popular statement. Although understanding the technical aspects of a particular software can benefit the user greatly, the vast majority of users only want to know what they need to know to get by. As a software tester, I need to know more about the technical side. For me, working with the programmers to decipher new vendor code is essential because there are so many scenarios that can occur during health care billing. Learning more about the code can help me test more effectively and understand the results and limitations of the software which is essential when dealing with a seemingly endless number of Fed Regs.
The analogy of a manual and bathroom key is classic. I thought that it was important to also note the two failures of documentation: "failure to write so that the user can perform the task easily, and failure to write as if we were speaking to real human beings" (383). Remembering this can be hard, so I try to look for it not only as I write but as I revise. I often have to revise multiple times and look for specific problems every time (like Barker suggests--looking for active voice, parallelism, etc.). I found out that in my project, I was writing about actions and functions (385). I made sure I was writing about actions when doing the instructions and about functions only when I thought it was pertinent to note what the functions were (in the appendixes). This way, there is a balance for the user in knowing how to do something and why they need to do it.
I liked Barker’s discussion of writing about actions rather than functions. The hyperlink definition example was good. It clarified the difference between writing for function and writing for action. I get it that the hyperlink button inserts or edits a hyperlink. Never thought much about it. But I understand hyperlinks and know how to use them. An inexperienced user would find little help in that definition. The rewritten statement about the hyperlink gives a better definition and actually tells the user what they can do with that button. The second definition gives the user the tools to help them do their work. It makes sense to not only define but show usefulness, and I see where both can be effectively combined.
And I get it about writing in the active voice. I know it makes for easier reading and comprehension, but I slip into passive voice constantly. I think I’m a product of having worked as a legal secretary for too long. Everything was written in a passive voice with plenty of words that are almost archaic.
I don’t quite understand why it’s so easy to write in a passive voice. I struggle with that in all my writing, school and work both.
I agree with Kathy's comments about active voice. Until you take a tech comm course, it seems like you are always taught to use passive voice. All through high school and any creative writing courses in college- passive voice and wordy language is encouraged. It is hard to get out of that habit.
I thought Barker did a good job of explaining the importance of the concept of writing about actions rather than functions. How true this is, we all need action statements to help us to understand how we are to use the functions of software. Barker also emphasizes the use of Active voice, I agree with Hilary on this one. I have received more information on the use of active voice since taking tech comm courses.
I think it's always important to make sure you get the language right. I agree that I have learned more than I ever have about what voice I am using since taking Tech Comm classes. I also like some language that Katy pointed out. I think a lot of the times we worry so much about writing that sounds very professional and technical and we tend to forget that we are talking to real people. I also think that writing too eloquently risks that the task becomes over complicated and therefore harder than it has to be.
The real problem I have with graphics is consistency; I keep trying to change things so the each bar graph is unique from the others so that they don't all run together. In retrospect, that probably just made them harder to read.
Post a Comment