Barker Chapter 4 – Writing to Support-Reference
by Mary Dobbins
Chapter 4 deals with the three main levels of support: teaching, guidance, and reference. The level of support used is determined by user behaviors, questions, and needs. The various forms of reference are described as follows:
- Appendices – highly detailed, technical documentation such as error messages explanations, filenames and extensions of files associated with the program, troubleshooting tips, compatibility information, fast-key options, printer driver charts, and FAQ
- Readme files – installation details, changes not included in the manual or online help, new features in program, revision histories, errors in manuals and online help, file descriptions, contents of directories, installation tips, and compatibility requirements
- Job aids – shorter document that may include keystrokes, definitions, brief processes, command summaries and other useful information
- Flipcards – contains brief program information on a card that fits on a monitor. Typically, flipcards are easy to read, contain a lot of valuable information, use colored headings, are unique and interesting, and offer easy access to information
When developing references, you must decide what to include. The text suggests:
- Commands – explanations of set and format commands, special procedures, and toolbars
- Interface elements – explanations of menus, keys, screen labels, and rulers
- Definitions of terms – glossary
References should be written in a consistent pattern and arranged in a manner that makes sense to the user such as alphabetically or preferably, menu by menu. The text indicates it is necessary to show the user how to use the references and also to understand how the typical user will use the references.
9 comments:
It's been hard to gather my thoughts to blog about this chapter. I think it's because I'm not a detail oriented person but this chapter makes it clear that providing the audience with the best-fit level of support is important. And that includes details. My work group and those we support have all sorts of 'job aids' such as a cheat sheet for task procedures so that all the required information is always included when a task request is made. As long as everyone follows the 6 simple steps provided on the cheat sheet, I can compile and categorize a year's tasks so we can measure the workload. This job aid has proven to be effective. Barker writes about many support methods that I usually don't use in my work life but I do use appendices and glossaries a lot in my coursework. I agree with him that reference users want efficiency and immediate usability and this fits with my lack of attention to details. I just want the information I am looking for and I need it in an easy-to-find structure. Now I just need to practice including the details, such as glossaries provide, to make sure my instructions provide information for different user needs.
The one element that Barker streses in each of his chapters so far is consistency. I think this is one of the main details to keep in mind when writing procedures and policies. I have developed a better eye for this as I have been reviewing documents at work. I have been surprised at the number of documents that may refer to the facilities manager in one document, and Maintenance manager in the next.
I too think that one of the common themes we can take from Barker is that consistency is important. I personally feel that the mark of writing good policy and procedures is that the user cannot tell the difference if you've written or someone else has. I think it's one thing to be consistent when you do your own work but it's a whole other issue when it comes to being consistent company wide. Being consistent in anything is a good way to create familiarity and therefore eliminate confusion.
Robin and Erik both mentioned the common theme in Barker's book, and especially this chapter, is being consistent, regardless of the method of reference you are using. I agree with that and with putting yourself in the place of the user. Oftentimes Barker suggests you remember back to the time you needed reference information, or how to figure out a software program and what types of documentation worked best for you. That is another recurring theme...remember the user. It is like previous classes I've taken where the emphasis was on your audience. This is no different and when you look at it from that perspective, a lot of documentation of software evokes the use of common sense along with the procedures we learn in these classes. In my small circle of friends, a few are software developers, and the interesting consensus among them is that they abhor documenting their software. Their enjoyment is in developing the program. Documentation takes a back seat. Many have said they would prefer to hands-on train than write up a manual on how to work the program. I've often wondered why programmers think documentation is so disagreeable to them when most take huge pride in their applications. If they applied what Campbell suggests, write as you would speak, maybe documentation would not be the evil task they possibly consider it to be.
When I was writing my procedures and documentation project I also often thought back to previous store handbooks, manuals, and even software documentation to help me write to the user. I agree with Kathy, also having a few friends that are developers, one that I can think of develops software and he hates having anything to do with documentation. He enjoys developing but leaves the rest up to the writers of the company to document it. I would think that he, of all the people there, would know how to document it best - he disagrees. That is one reason why I am minoring in Tech comm, so I know how to document software once I start a career in the information technology field.
This chapter stresses consistency and details in every part of developing a document. It is important to follow the same format throughout, and make sure that it is one the reader/user can follow as well. The section about job aids was most interesting to me because new users would find this most helpful in a job. I can picture job aids that would be helpful in my job as well, but no one ever made. This chapter emphasized how to make reference documents easy-to-use for the reader and facilitate their needs for quick-reference. The different graphics in this chapter (flip cards and job aids pg 98-99) also give me an idea of how to visually design this type of document for a reader to use. I like the idea of having visuals as well as word descriptions for tasks because it can appeal to the widest audience of users.
We use job aids all the time at work. It is necessary as our job changes all the time. We store them in our computer and print out copies to keep in our binder. Some job aids include fonts ands sizes as well as various short cuts and commands we use on a daily basis in In Design. Command information is extremely important in our documents, and should be better organized I think. This chapter does a good job of explaining different categories of writing such as what to put in for appendecies, but consistency is key. We always say, "At least you are consistent." Even when making a mistake. This is something I have had to get a grip on because I am used to going back and forth on different formats and styles (AP vs. Chicago Manual of Style, etc.) It is easy to get confused at times, but I am getting better at consistency and it is huge when writing procedures of any kind. I have never heard of flipcards until this chapter, that is an interesting concept. I will have to look further into that...
This chapter makes references sound like fruit cakes; dense, and packed with valuable nuts and dried chunks of knowledge. Of course, nobody really eats fruit cake unless they have to, and the same goes for support documents.
Post a Comment