1. Part Three The Tools of Software Documentation Chapter 10: Designing for Task Orientation Chapter 11: Laying out Pages and Screens Chapter 12: Getting the Language Right Chapter 13: Using Graphics Effectively Chapter 14: Designing Indexes and Searches

2. Chapter 10 Designing for Task Orientation

3. Guidelines: 1-Follow a problem solving process: starting with a goal and ending with a solution: - Set goals for the document based on user analysis. (what level of usability, what do they need to understand, how do they need to perform) -Identify techniques that would meet the goals. (see next two slides to see what elements you need to help meet those goals) -Mock up examples of potentially useful designs. (prototype of page or screen) -Test and review, evaluate with users. -Decide on a design with confidence.

4. Meet task needs, In any task oriented documentation you will find a step by step procedures called tasks that user can follow to perform useful work. You should organize these tasks so that they match the pattern of activity your user will understand as logical. Remember what is logical for one user won’t appear logical for others, because they do different kind of works.

5. The following are examples of methods (ways) which you can use in order to organize your tasks to meet user’s needs: - degree of difficulty, beginning, intermediate, advanced; used for tutorials. - sequence of use, starting, processing, analyzing, printing; used for tutorials, word processors and spreadsheet. -jobs or tasks; job a, job b, job c; used for programs with distinct users: administrators, clerks, executives. (ex. processing receipt) - job related topics; topic a, topic b; used for large systems fewer user types, identifiable topics. (ex. Business and finance, computing) - user groups; group a, group b; used for educational programs, networks. (Ex.Teacher guide, student guide)

6. Elements of document design: - headers, help users locate the information within the context of the entire manual. - introduction, helps users see the workplace application of function. - heading, help the users see the hierarchical structure of information. - icon, helps user recognize key information. - cuing pattern (italics, bold),helps users recognize key information. - numbered steps create clear areas for commands - lists and tables helps users decide how to apply program functions to workplace tasks and give users a sense of control. - page numbers, helps users navigate among abstract concepts.

7. Elements of online help design: - color, helps users recognize task name. - introduction, helps users apply functions to workplace tasks. - icons, helps users identify screen elements quickly. - cuing (bold), helps users recognize key strokes easily. - hypertext links, helps users access related commands and tools.

8. 2- Review the user analysis: the following are design suggestion for each element in the checklist in chapter five: - Design for different groups When designing for different groups consider the following: · Navigational aids- make sure the user groups get to the information pertinent to their needs. These could include special statements, directing users to the sections of the documents, list of figures and tables, headers and footers. · Scenarios- give each group a role model. · Icons- identify information for each group. · Metaphors-make implicit relationships to the workplace so users can see and feel the document is familiar to them.

9. - Design for specific program issues: Design for a specific program issues: · Job performance aids cover technically or repetitive tasks. · Background information to meet special needs. · Special forms can help users collect information in the field for later inclusion in the document.

10. - Meet the user’s task needs, Illustrations, layout design, examples of usage, special document sections, and tips. - Meet the user’s information needs: This requires you to understand how users manage information within a job setting. There are several strategies you can use: · Explanation so the user understands their use and importance. · Provide examples that illustrate workplace uses. · Meet efficiency goals/command summaries for efficiency by providing things like shortcuts, macros, etc. · Identify functions that relate to information management and communication work

11. - Match the user’s computer experience, Describe the kind of novice, experienced, and expert behavior exhibited by the user. Consider the following: -novice, tutorial covering basic functions, definitions, full screens, sample files, keyboard template. -experienced, problem solving support, short cuts. -expert, quick reference card, command reference, troubleshooting support. - Enhance the user’s subject matter, Take advantage of the user’s knowledge of the subjects by doing the following: · Special glossary of background terms · Index entries linking background terminology to program functions · Special booklets/sections describing background concepts · Elaborate examples with explanations of key concepts

12. - Leverage the user workplace, Try to incorporate the following to help new users, Getting help from coworkers, Suggestions for support group, and Descriptions of network use. - Meet the user’s learning preference, Learning preferences are connected to the choice of media as well as design: - Instructor learning – For instructors use lesson plans, overheads, etc. For the learners use workbook, note pages, diskette. - Manual learning – Tutorial manual, list of learning objectives, samples files - Computer-based learning – Programmed computer-based training modules, etc.

13. - Meet the user’s usage pattern, Describe the patterns users will exhibit in using the software in terms of regular, intermittent, and casual usage: - regular usage, section “about this manual”, interrelated examples. - Intermittent usage, help system, support for problem solving such as tips and scenarios, troubleshooting. - Casual usage, quick cards, scenario suggesting mental models of program usage and applications, keyboard templates.

14. 3-Acknowledge production constraints: Decide on what design features you would like to have and what you can afford to have. You need to know you limitations before planning. Some constraints are: Writing tools, Production tools, Human resources, Budget, and External considerations. See table 10.3 for further explanation of the constraints.

15. 4- Design the documentation as a system, test it and review it, In this phase you evaluate through reviews by clients and sponsors and test problematic areas in a lab or field test. To test your design you can follow these steps: a. Mock up pages with access elements on them and field test them. b. Consult the chapter on testing for was to do quick usability tests. c. Decide on a design based on logic and experimentation. Try out ideas on users, involve users in the process will eliminate alternatives that would not work for them. Users rejected document because it did not meet their expectations. Give users sample pages and find out which one they prefer. Preferences mean a lot in manual design. Examine existing documentation, in software stores, bookstores, libraries, and workplaces.

16. 5- Follow a Design process for Online Help, - identify and list online help topics, see figure 10.5 for an example of topic list. - determine the interconnected elements. - decide what design features to use, such buttons and links for the online. (indexes, TOC.. for print document)

17. The Design Problem: The problem of software design results from each reader needing to apply the system to a multitude of tasks. And because of the linear bias in most information presentation – pages, screens- users expect information organized linearly. To meet the goals of efficiency and effectiveness we need to accommodate the one to the many. (one book many users)

18. What does guide mean? Is it the manual will guide the user to the answer? Or does it mean that the manual will guide the user through the program? Or the manual will guide the user to the many ways to use the programs? No matter what was the answer, it as a jungle (manual) or a jungle (program) or a jungle (the job).

19. For an attorney who needs to make the text shift to the right with word processor, the manual has to educate her to what term this program uses to describe her problem. (indentation, tabs, margin). To get some clear path through that jungle consider the following: - accommodating groups of users: We must consider the degree of experience among types of users, each type will react to the manual differently, so you have to have a set of manuals in one book to satisfy sets of expectations.

20. - psychological differences, the readiness to reject, the expert user has more patience with program, more confidence than the novice user. (novice:This word processor does not allow you to move text to the right.. Imagine that) the expert will say it ( This word processor must have a way of moving text to the right; they all do, I just haven’t found yet). Novice has less experience with documentation, they get lost easily. -Different informational needs: (the factor of previous experience), margin and indent, typewriter and word processor. The experts would recall the different terms of the task. The novice will look under “margins” because of the lack of experience in computers which used “indentation” instead of “margin”.

21. The designer needs to use a variety of features such as glossaries, cuing, graphics, and type styles to catch users of limited experience and get them on track. role-based types, to determine this, we need to know what kinds of jobs the user perform with the software. (operators, installers, evaluators). The writer should segregate the info into the appropriate sections and then use adequate cuing to make sure each user type does not wander “get lost” in the wrong section.

22. How people solve Problem using computers? The more we know about how people get the program to do what they want, the better we can make their use efficient. (common error among the arts students is to draw eyes in the upper portion of the face). The more we know about the common errors made, the more we can design documentation to counteract them.

23. Matching the user’s problem-solving methods There are several issues to consider: - No one carefully reads more then 2 sentences at a time. - Solution: Make paragraphs short. Include tables and lists whenever possible. - Most users begin using the table of contents before they ready the manual. - Solution: Make table of contents complete. Use abbreviated, complete and chapter-by-chapter table of contents. - Most users go to the manual or help only after they have failed to perform tasks. - Solution: Describe error recovery clearly and completely.

24. - Most readers do not read instruction first. - Solution: Replace introduction with information about users needs, special documents features, or helpful routing information. - Most readers do not read any sections in its entirety. - Solution: Tell users which section to go for particular tasks/problems. Make sure all descriptions of tasks are complete for performing task. Repeat important information.

25. -Successful users of computers got to be so, ONLY after making an unusual number of mistakes. This make a sense when you think about it; we reason and learn by taking the wrong track and starting a gain. Solutions: - expect errors, make sure you tell the reader to get out of trouble, focus on real tasks, avoid made up example, slash the verbiage, encourage user to try out a function to experiment, let the user know how to recognize when mistake occurs.

26. How mental models work: Reading a manual that talks about a system of which you have no prior knowledge is like listening to traffic report about a city where you don’t live in. You understand the report but it does not match the city map in your mind. The problem with computer manuals occurs when the manual contains a design of the system that does not coincide with the one on the user has in mind. A good manual, in this case, should bridge the gap between the computer program’s “point of view” or model and that of the user.

27. - A good manual, in this case, should bridge the gap between the computer program’s “point of view” or model and that of the user. - Solution - include graphic overviews, use analogies, the same terminology as the user, identify tasks the user recognizes and performs, evoke (elicit) the user’s goal and achievement model, avoid elaboration on technical explanation with novice users, frequently suggest ways a function can help the user.

28. The design guide for printed documentation: 1- navigation, Navigational aids are elements of a document that tell the reader where to go next for what kind of information. Make sure you include navigating as organizing feature only after you have examined your user’s tasks carefully. 2- Cross reference: point to other sections or chapters with related info. when you create a cross reference, you insert a field that point to a bookmark in the target section, so every time you update the fields of the document, the program automatically update the cross reference.

29. 3- Running Headers and Footers This may include: chapter and section names and numbers, book title, graphic cues and icons, task names, and color to indicate sections. 4 -Layering, is having two versions of information on the page at once, to satisfy more than one type of reader: - put keyboard equivalent next to mouse instruction, put commands in the of TOC along with the terms, put advanced instruction or definitions in tables alongside instruction for intermediate users, use one column of instruction for beginners and other for advance users. 5- Lists of figures, tables and screens, it should appear early in the manual, use the same format as the table of contents.

30. 6- Indexes and TOC : They are the two most important user tracking and navigation devices. TOC describe the contents of the document from a task perspective. The index usually contains abbreviations, synonyms, slang term, substitute words, and user questions. 7- Headings, icons make good heading elements, because of their visual nature, the following are good guidelines for including headings in manuals: - support workplace application, use consistent fonts and style, make heading task oriented, use appropriate graphical cues, use san serif (plain) font, in bold.

31. 8- Document overview, introduce the first time user to the manual, how to use it and how it works. Include a section “How to Use This Manual” 9- Parallel Structure: useful pattern to help the user identify information easily, ending with “ing” like installing, configuring. 10- Cuing: it refers to the technique of including visual patterns to make a certain kind of information memorable. - cuing with icon, cuing with rules.( solid or gray lines), cuing with fonts, cuing with CAPS. 11- Interrelated Examples: Interrelated example means when you follow the same example from one procedure to another. Using interrelated examples provides the following benefits to the user and to the writer: creates a learning curve, ties the document together, and makes the writer’s job easier.

32. Solution to the design problem for online documentation: 1-non scrolling regions, appear on top of screen and stay there. 2-keyword and whole text searches, search box. 3-links and jumps, allows user to go from one topic to a related topic. Online help system have a definite advantage not only can link topics together, but you can allow users to go back and forth between topics. 4-expanded text, also called “stretch text” allows you to embed more detail into a topic so that the user can click on the expanded text to view the detail.

33. 5-indexes, show an alphabetical view of all the important topics and terminology used in a help system. 6-pop ups, to handle glossaries the user just has to click on the term to see its definition. 7-context sensitivity, the ability of a help system to present info based on the current state of the program. User will go from a problem with a screen or a field to the appropriate help topics contain the solution. 8-histories, history buttons allow user to trace their steps, easily go back to previous topics.

34. 9- browse sequences: the system displays forward and backward arrows to brows a series of related topics. (topics related to printing, formatting). When the user clicks on a topic that is part of a browse sequence, the system display forward and backward arrows. 10- bookmarks/ annotation: sticky notes, piece of paper for books. With new online help system you can incorporate bookmarks. The same goes for writing on pages for books and online. (not only you can annotate on line systems, you can collect your annotation, print them, revise and delete them, or share them with others).