Barker Chapter 3: Writing to Guide – Procedures
The chapter discusses the organization of software documentation into 3 levels of support: teaching, guidance, and reference. It also covers the formats found in manuals and online help: standard, prose, parallel, and context sensitive.
Guidelines:
Relate the task to meaningful workplace procedures
Determine how much information your user needs
Choose the appropriate procedural format
Follow a rhythm of exposition
Test all procedures for accuracy
Relating the task to meaningful workplace procedures means writing the procedures so the user can see how the steps of this task can be applied to things they actually do in the workplace. Show them how learning this step can be used in real-life situations.
Determining how much information your user needs can be determined with a user analysis (that will be covered in a later chapter) to assess the level of detail needed in the procedure, which also can vary by the complexity of the task you are trying to teach. The author used descriptions like “rich with detail” and “sparse detail,” and gave examples how to make detail-rich procedures:
Screen shots
Cautions and warnings
Tips for efficient use
Tables showing options the user can take with specific steps
References to other sections of the manual or other resources
Explanations
Choosing the appropriate procedural format explains the different accepted formats for manuals and online help and suggests a well-designed procedure sticks to one or two accepted formats for consistency, but warns that you fill find inconsistencies in manuals today. The different formats were discussed giving both advantages and disadvantages of using that particular procedure.
Standard Format
Prose Format
Parallel Format
Embedded Help
Following a rhythm of exposition means a pattern of step, note, and illustration – I give you a command, I tell you how the program will respond, I illustrate what happened, and then I tell you the next step.
Testing all procedures for accuracy are evaluative tests. Get an actual user or as a last resort, use yourself to make sure the steps reflect the program. Be prepared to discover things you may have overlooked or left out.
Discussion section discussed what constitutes a procedure. Procedures fulfill the user’s purpose which is how to use the program. Procedures function on different levels:
Guidance level
Support level
Teaching level
The parts of a procedure contribute to the overall task orientation of the procedure.
Task name- should describe the job a users preforms
Overview-introduction
Steps-most important because it directs the user
Elaborations-explination of steps
Options-save time and space
Screens-gives a way for the user to know that they are looking at is right
Subscribe to:
Post Comments (Atom)
9 comments:
I really like the fact that this chapter talks about testing your procedures. I can really appreciate when specific, detailed procedures are documented. In some of the software manuals we receive from our vendor steps are sometimes out of place or missing entirely - it drives us crazy! If anything has hit home to me, it is documenting and testing your documentation through users' eyes.
As I read this chapter I kept thinking back to the recent implementation of Magic software in my workplace and the chaos that followed. All employees (3000+) were required to attend individual training sessions to introduce us to Magic and demonstrate how it would impact our jobs and our access to personal information. There was only one class left with openings when I signed up and this class was a mix of employees from finance, business, managers, and all level of employees from various departments. The class was geared for managers and those who were not managers, myself included, sat through a training session that taught us nothing pertinent to how Magic would affect our jobs but it did provide training for managers on how to complete timecards.
I think it would have been difficult to sort all employees into specific training sessions that addressed their work group requirements but I came away with no knowledge on how to use Magic or how it would affect my job. The program did go live and there seemed to be a lot of confusion with no online help available for questions from my work group.
I think Baker provides a good set of guidelines, as Emily noted. I do think the large volume of employees with differing needs played a significant role in the confusion that resulted after Magic went live.
This chapter gave great insight into analyzing the users needs to determine how much information should be included in a procedure. When our company was trained for the use of Documentum, the trainer provided a lot of screen shots that helped facilitate a learning environment for the employees.
I too see the importance of usability testing of procedures and it is something that I would like to see implemented at my place of employment.
I agree with Joan and Mary both, that some of the training we receive in software manuals and in live trainig does not provide the necessary information to the varied needs of the user. Our company is part of a large conglomerate, but yet we are a smaller entity that allows for us to train in small groups that creates an easier training environment for us. We do get divided into groups, manufacturing, office, finance etc.
I really wish I could have had this chapter as a reference when I was writing my policies and procedures for James Tower. Certain things I did do that were discussed in the chapter. During my BA and tech writing internship, I used numerous screenshots to explain to the consultant what we were working on and steps for each screenshot. Sometimes my guides would get so specific I think it was overkill. This manual was over 300 pages. I think anyone would get confused evenutally, which is why we had a help center to discuss problems, because many people did not care to thoroughly look at the guide. Testing procedures is also very important before they become permanent. One of the documents I was working on was ever changing, and I think there could have been a more efficient way to work on this large procedure for this software program.
I also appreciate the testing of procedures as they are introduced. I think it's important to make sure whenever you are creating something technical comm related that everything be in good order so that in can be taught effectively. I also think whenever implementing new software of procedures it is very important to aim and hit the correct target group. Like Joan said, sometimes it's impossible to have individual training sessions for certain portions of the software but I feel that you may as well receive no training if you are learning stuff you aren't going to necessarily need and be using regularly. Repetition of the steps during implementation will create familiarity and therefore lead to successful integration.
This chapter makes you think about how to write your procedure. I recently had a problem writing a procedure at work, and I had a hard time coming up with how technical to get with each step. You don't want to go into too much detail, but you can't be too vague. This chapter is helpful because it spells out different style to write procedures. This will really help me in the future.
I learned quite a bit by just reading this chapter. I like that fact that the book uses lots of pictures and illustrations to give you a clue of what they are talking about. I don't really have any real-life examples of where I would of benefited from knowing any of this knowledge, but it gives me ideas of what formatting I learn best from. Standard formatting I think is what most people learn fastest with, I also like the parallel style. Now when I think about it, I have noticed some pretty poor procedural writing in some of the software that we use at work which generates department reports and sales figures. Some of them are so hard to understand that its easier to just do the trial and error method.
Screen shots are one of my favorite ways to show how to use a program. I was training someone on how to use the computer system and (without really knowing it) I developed a screen shot for them to reference on the most-used screen of our computer system. I also agree that the emphasis this chapter placed on testing and looking for things that the author may have missed in instructions is very helpful for the user. The overview of different visuals that the author can use when writing provides easy access to different kinds of learners--the learners that need just a quick reference and the new learners that need more detailed instructions. Training and teaching new employees is key to a company's growth and this chapter outlines what to do in the process.
This chapter brought back fond memories of the peanut butter jelly sandwich experiment I've had in a few classes. It's annoying to discover that the instructions you've written just don't make sense for other people.
Post a Comment