Notes for Barker Writing Software Documentation: A Task-Oriented Approach, second edition


Chapter 1
Understanding Task Orientation

(6) The concept of user-driven
design means that the organization of a manual comes from the user's needs rather than from models or templates of what a user's guide should look like.
(10) [Task orientation is] a design strategy for software documentation that attempts to increase user knowledge of and application of a program by integrating the software with the user's work environment.
(15) Applying an action/operation framework to computer work can help documenters see the kinds of complex tasks they need to support.
(16) Challenging the user often requires teaching computer skills in the context of a person's job so the user can see the benefit of the software.
(21) Of the three main forms of documentation, reference documentation is more purely descriptive of the program itself than of the user of the user's application of the program.
(23) [The default user] is defined as a person who uses the menu items and functionalities of a software program.


Chapter 2
Writing to Teach: Tutorials

(34) Objectives should appear as actions the user needs to accomplish and the skills the user should learn in order to accomplish them.
(36) The guided tour informs and persuades: It tells of the program features, and also helps convince the user of the usefulness of the program.
(37) [Demonstrations] illustrate some specific parts of a program that emphasize a real-world application of a program or an important user case.
(39) [Guided exploration is a] well-researched form of tutorial based on the idea that users need to control the learning experience.
(39) [Instruction manual consists of] lessons framed by elaborate objective and summary statements.
(53) The direct, elaborative approach to teaching accommodates this tendency to make mistakes by minimizing it.
(54) Users read to locate necessary information rather than from the front to back like you would read a novel.


Chapter 3
Writing to Guide: Procedures

(67) [With layering] you provide both levels of details on the same screen.
(68) [Screenshots should] show the actual user interface, what menus to display, and what choices to make.
(78) [Flyout help] this method of representing tasks does not depend on constricting descriptions of procedures, but instead reflects the dynamic nature of actual workplace decision making.
Especially when the goal is learning programming, teaching level of task orientation in tutorials must be foster remembering.

(82) The teaching level of task orientation, which you accomplish through tutorials, has as its goal the internalization of concepts: You try to get the user to remember the features after the lesson finishes.
(82) Guidance-level documentation also differs significantly from
support-level or reference documentation. With support-level or reference documentation, the user defines the task and goes to the documentation to get an essential tidbit or chunk of information . . . [such as] the type of data to put into a specific field.
(82) [Guidance level procedures help the user] know what keys to press, what reports and screens will look like, and how to get out of trouble . . . [mainly] leading by the hand.
(83) The task name should describe what job the user performs, not what functions he or she uses.
(87) Rich procedures would include a screen for the starting state of the task, one or more screens illustrating how to use interface tools, and a screen indicating the result of the task.

Chapter 4
Writing to Support: Reference

(97) [Job aids are] shorter forms of reference documentation that include keystrokes, definitions, brief processes, command summaries, and other information useful to computer users as they are working.
(102) The task orientation of your reference section may depend on your ability to build a set of elements that meshes with your user's expectations and needs.
(102) [Establish a pattern] repeating the same set of elements over and over so the user learns to identify how each element of an entry functions.
(111) The elements of a reference entry do much of the work of establishing the task orientation of your manual.

Chapter 5
Analyzing Your Users

(118) It helps you find out how your software fits into the pattern of workplace activities of potential users in productive and appropriate ways.
(121, Figure 5.2) Guidelines for conducting a user analysis
1. Choose users carefully.
2. Anticipate transfer of learning: Study users before and after using a program
3. Research professional behaviors.
4. Write use cases.
5. Plan interviews carefully.
6. Involve users in all phases of the project.
7. Identify document goals.
8. Tie the user analysis to document features.
(140-141) In preparing a user analysis, you basically ask the following eight questions:
1. What tasks will the user perform with the program?
2. What are the user's informational needs? (What information does the user need? How does the user communicate? What work motivations affect the software user?)
3. What are the user's work motivations?
4. What's the user's range of computer experience: novice, experienced, expert?
5. How much does the user know about the subject matter of the program (for example, accounting, writing, designing)?
6. What's the user's workplace environment: the user community (for example, organizational structures/other software users)?
7. What's the user's preferred learning preference (instructor/manual/online)?
8. What's the user's usage pattern (learning curve, regular, casual, intermittent)?
(147) What motivates users professionally will also motivate them to do well with software – to assemble interface elements and basic operations into meaningful sequences leading to an objective.
(149) The novice user basically exhibits very different degrees of anxiety and receptivity to different interface and media types than does the experienced user.
(149) In their minds, they do not have elaborate, highly differentiated models of how computers work.
(150) Novice users often do not see a clear relationship between the program and their work. . . . And because they don't see the value of using a program, they often form a negative attitude toward new software.

Distrust may be a standard attitude of novice learners toward textbooks; try linking to success or failure of spreading general programming skills (Kemeny; comparison of early personal computer manuals).

(150) They distrust manuals, feeling overwhelmed by their usually technical nature and arid prose. Manuals appear to be truth arranged in a meaningless way.
(158) [FAQs] actually respond to questions real users have asked that are not answered by the standard help topics.

Chapter 6
Planning and Writing Your Documents

(175) The steps of the task-oriented documentation process involve building all the documentation products around workplace tasks you specify in the user analysis and user scenarios.
(186) The operations of the programs have been grouped according to how they would be used by actual users.
(187) [Organizing topics in terms of complexity rather than alphabetization] suggests a growth in learning of program features, something that the user would naturally expect as he or she became more powerful with the program.
(204) It is very difficult to say at the beginning of a one-year project exactly what the user will need and so the program and documents tend to diverge from the original requirements.
(205) Once the right design is found the program is complete. User requirements are refined as the program unfolds.
(206) The object-modeling method, as it is sometimes called, identifies user needs through a development tool known as a “use case” model. The use case model is a plan that tells exactly how the user will employ the program in the workplace. . . . Writers in a project using this development method can use the use cases as actions and build their documentation around the same objects as the program.

Chapter 10
Designing for Task Orientation

(306) The main design element is the outline of the information in your documents because the outline embodies your most innovative and user-oriented ideas.
(323) [In books] the answer occurs in only one place in the manual, but there are many ways she might try to find that answer.
(326) Make descriptions of error recovery clear and complete.
(343) [Expanded text] called 'stretch text' allows you to embed more detail into a topic so the user can click on the expanded text link to view the detail.

Chapter 11: Laying Out Pages and Screens
Degree of Structure

Does it make sense to compare Timex User Manual and Applesoft Tutorial on what Barker identifies as “Degree of Structure”?
(362-363) Researchers have determined that readers locate information in computer manuals (in fact in all documents) by remembering the physical location of the information on the page, rather than the more abstract terms of chapter or section numbers.
How to Look at Pages and Screens
(363) You should always give a manual the flip test and register an impression of the overall layout of the book.

Let's do this for the old computer manuals.

The Idea of Body Text
(377) When you select type style, font, and size for the main text portion of your document, you make one of the most important choices in document design: You determine body text.
Non-Body Text
Headings
Hints, Notes, and Cautions
User Input, Computer Output

(379) For input, most users expect the Courier font because it resembles typewriter text, and the analogy of the keyboard to the typewriter helps them understand that they should now use the keys to enter a command of a file name, or whatever. For output, warnings and other messages may catch the reader's eye better in a small-sized sans serif font like Helvetica.

Chapter 12: Getting the Language Right

Guideline 5: Add Operational Overviews
(389) Your 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.

Discussion
How Do We Process Language?
(391) The language of the document should help appropriate the energy the person puts into the task. It should fit into the dynamic psychological pattern of effort and reward, exertion and satisfaction.
Performance-Oriented Language
(391) The bet that the reader will slog through extended passages for simple information has not paid off for many documenters. Using the active voice, using the you pronoun, and using the imperative verb add to the performance orientation of the style.

Chapter 12
Getting the Language Right

(389) Your 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.
(391) The bet that the reader will slog through extended passages for simple information has not paid off for many documenters. Using the active voice, using the you pronoun, and using the imperative verb add to the performance orientation of the style.
(391) The language of the document should help appropriate the energy the person puts into the task. It should fit into the dynamic psychological pattern of effort and reward, exertion and satisfaction.
(391) Using the
you pronoun, and using the imperative verb to add to the performance orientation of the style.
(395) You should anticipate those terms that your readers will most likely will recognize and build in crossover techniques, such as using synonyms in parentheses, in the index, in tables, or just in text.

Chapter 13
Using Graphics Effectively

(408) Use more cartoons and animation with novice to experienced users and technically oriented charts and diagrams with experienced to expert users. Respond to the questions you think your user would have about a task by designing graphics to support those questions.
(411) Metaphors are workarounds for the general abstractness of computer terminology.
(418) [Conceptual overview] illustrates what occurs during processing. The diagram helps the user anticipate the process and fit unexpected events into the overall picture.
(425) You should arrange and design [images] so they convey the structure of the meaning you intend.
(430) Showing the user's environment like this can provide a powerful image in documentation because of its direct relationship to productive work.

Barker, Thomas T. (1998). Writing software documentation: A task-oriented approach. Boston: Allyn and Bacon.


Barker, Thomas T. Writing Software Documentation: A Task-Oriented Approach. Boston: Allyn and Bacon, 1998. Print.