The first item a writer should keep in mind is Relating tasks to meaningful workplace activities (64). Barker continues to say that procedures are parts of a whole and should be written with the clarity of how a procedure fits into the larger picture.
Determining how much information the user needs (66) is the second item on Barker's list. Detail in a procedure increases with the degree of difficultly of the procedure. A good rule of thumb is the more detail, the more visuals and explanations should be present. Barker outlines some different ways to enrich procedures:
- Layering information for different users, those who already know part of the procedure and those who are learning for the first time.
- Screen shots provide the users with a visual of what to do next.
- Cautions & Warnings provide the user with advanced knowledge of how to retrieve information should it be lost.
- Tips for efficient use help the user by offering an alternate method for accomplishing a task, or elaborating on a step or command.
- Tables allow for efficient organization of information. A few uses for tables in procedures are to present information on features and uses as well as terms and definitions.
- References to other sections of the manual or procedure or other resources
- Explanations of any step or command
Choosing the appropriate procedural format (72) can have a major impact on how well received your procedure is. Four formats that are covered in this section.
Standard format which contains steps, notes, screen shots, and other elements left justified in one or two columns in a sequential order from first to last. Advantages of this format are its recognizability, its ease of flow from one page to another, the ability to easily re-number tasks, and the easy to see steps. Some disadvantages are the space it may require and the potential to be confusing if complex steps need to be mixed with simple steps.
Prose format puts steps in sentences and paragraph forms making it look and feel more conversational over Standard format's command approach. Advantages of prose are the relaxed tone, saves space, clarifies simple, basic steps, accommodates experienced users. Some disadvantages are steps buried in paragraphs, lengthy explanation of individual steps, inability to accommodate graphics, and the lack of support for novice users.
Parallel format shows a screen with the fields empty and parallels the field names in the steps that follow. This format is nice for programs with complicated data fields of dialog boxes. Some keys to parallel format are to keep terminology consistent, cue terms to the screen, discuss one screen at a time, use plenty of examples, explain the format to the user. Advantages of parallel format are the organizational benefits, great for complicated screens and dialog boxes. Disadvantages are it doesn't present the information in step by step format, it can not be used for all procedures, it may confuse users, it has to fit on one page.
Embedded help is the name for "interactive assistance" found in most programs today. Uses for embedded help are tips for effective use (reminders of keyboard shortcuts or suggested file names), cue cards (brief explanations of buttons and fields), short animated descriptions, and trouble-shooting tips. Different types of embedded help are:
Flyout help Help that appears in a box or panel on the screen at the user's request.
Interactive flyout help. This form monitors the user's progress in filling out a dialog box and highlights one step at a time until the procedure is complete.
Do it for me help this form of help contains links within the online help procedure that activate the screen element or dialog box described in the procedure.
Field-level help Help that provides information on how to enter information in fields.
Interface help. Help information (brief instructions) provided in a designated section of a screen.
Pop-up definitions Pop-up definitions provide brief definitions of interface elements activated by a mouse click.
Roll-overs Definitions of interface items that appear when you move a mouse over the item and (often) pauseFollowing a rhythm of exposition (80) means consistency through out the procedure. An example of rhythm of exposition is:
- First I give command for the step.
- Then I say how the program will respond.
- Then I illustrate what happened.
- Then I tell the next step.
Test all procedures for accuracy (81). Always conduct usability tests for your procedure to ensure that they are effective and correct.
The Discussion section (81) of this chapter begins with what constitutes a procedure. Procedures are used when a user is doing something with the program. Procedures function on the guidance level by telling the user which key to press next, what screens and reports will come up next, and how to get out of trouble. Procedures differ from the teaching level because procedures are geared towards what should be done at any given moment rather than a tutorial of the program. Procedures differ from support level reference documents in that procedures follow a chronological or sequential order.
Procedures work by maintaining a general layout of information. Each procedure should have a project-orientated name, i.e. Opening a file, or Recalling a Record from the Client Database. The task name is followed by an overview or introduction that orients the reader to the use of the procedure, reminding the user what the task will allow them to accomplish in a work setting. Following the overview are the steps. This aspect is the most important because it is the period of time that affects the user directly. Great care should be taken when writing the steps so the user does not get confused or lost. Methods you can take to try to ensure the user fully understands your procedure are placing smaller actions in prose format under the parent action or elaborating on a parent action, i.e.
- Step 1. Choose Group from the Maintenance Menu.
- Step 2. Choose an action from the Groups dialog box. Once you have opened the Groups dialog box, you need to select a name for the group, then select a directory name for the group, then set the access code to either Open or Restricted.
- Step 3. Choose Close from the Groups dialog box.Elaborations help explain the steps as they are performed, which can help the user to avoid potential mistakes and perform procedures more efficiently.
Elaborations can also tell the user about alternative functions, toolbars, or keystrokes, how to tell if a step has been performed correctly, or where to look for additional information.Options or tables are suggested for use in procedures by organizing information and saving on space. These should be used when defining different keystrokes for the same operation, i.e.
To do this... Use these keys...
- Set colors to black and white Ctrl-M
- Revert to default colors Ctrl-D
- Adjust the brightness Ctrl-B
- Adjust the tones Ctrl-T
Screen shots, or screens, should be used when the user needs to see a tool in use or the results of an action. Screens are usually used for the following:
- Give an overview of the main panel of an interface
- Show the partial result of a procedure (a stage in the process) to help the user keep on track.
- Show the final result of the procedure to let the user know where the procedure ends.
- Show dialog boxes where the user has to make choices.
- Show toolbars indicating which tools the user needs.
- Show menus indicating what commands the user needs.
4 comments:
So far, I think this chapter is the most helpful. At one of my previous jobs, I decided to write up the procedures for making an index in InDesign. I mostly used the standard format and included screen shots and basic steps. I thought it worked pretty well, but after reading this chapter, I can see where my documentation needed improvement. I had notes and explanations listed as an actual numbered step, and it wasn't consistent at all. I'm glad we have the opportunity to try out documentation in this class because after reading this chapter, I feel I'm more prepared to tackle this assignment. Maybe I'll even go back and fix my InDesign Indexing documentation.
I was intrigued by Barker's views on the ordering of steps. On Page 85 he shows two documentation examples, one of which makes use of numbered sub-steps, while the other provides this information in the form of a solid paragraph of prose. While the numbered sub-steps would seem to make the process more clear, Barker contends that it is actually more confusing than the prose method in that it duplicates and interrupts the main sequence of steps. I agree that there are definitely times when smaller steps can be combined into larger steps to improve the overall usability and clarity of a document.
I've always like screen shots when I’m looking at a new program and figuring something out. When you see the picture it's good for a reference what you’re doing to make sure you at the right place. I’ve also found that rollovers are nice on a webpage by helping to keep the page less cluttered. I like this chapter because of all the information for formatting.
Again, I wish I had this during my internship because it could have helped me when I was starting to piece together the manual.
Post a Comment