The Key for Effective Documentation
To successfully communicate to users, documentation must do more than meet the user’s information needs, it must present the information in the same way the user processes the information. The design of software and it accompanying documentation must be reconceived so that the design is done from the problem-solver’s point of view. Effectively designing documentation requires the writer to: start with the user, answer the user’s rest questions, optimize all documentation as a single unit, allow for user mistakes, and consider how you present the information.
“The ability to create effective verbal and visual information for people to use according to their own needs is at the heart of the communicator’s role.” (12, p.38) Here lies the holy grail of effective software documentation. However, as long as the developer sees software as a series of screens with fields optimized to access a database, as long as the technical communicator sees it as a series of screens to be described field by field as long as senior management sees it as a series of reports that they needed yesterday for answers they need today, as long as IS management sees it as a steadily decreasing budget item, as long as users see it as something new they’ll have learn and something which may cost them their jobs, the holy grail will remain hidden in the mists.
We need to stop considering documentation, software interface, and online help, as separate entities and remember we are communicating with users. We must go beyond simple instructions and design documents that assist in solving real-world complex problems. We need to support the problem-solving strategies that address the user’s real tasks. Documentation for complex tasks means thinking big; it means considering and integrating everything the user sees: user interface, online help, error messages, and paper manuals. To accomplish this goal, we must do more than think about a program’s menu structure; instead, we must follow a different path.
Documentation researchers need to discover the conditions and real workplace tasks that require a user to consult a manual to make up for a poor interface and require document designers to become involved in interface development, online help design, or organizational training. (10, p.83).
To successfully communicate to users, documentation must do more than meet the user’s information needs, it must present the information in the same way the user processes the information. We can change appearances, but effective communication does not lie in appearances. Communication works at the level of assumptions, implications, and expectations. Effective communication means determining and providing answers to the complex problems of the real-world. Analysis should be stated “in terms of the behavior-shaping goals and constraints that define the boundaries of a space guided by their local and subjective performance criteria” (11). Dobin insists that to support problem solving for open-ended problems we must gain an in-depth understanding of the user and not the software. “The user’s vocabulary, the user’s reasons for looking things up, and the problems the user confronts must be clearly anticipated’ (3, p.89). Actually, if we define the conditions and real workplace tasks early in the project and then use that information to design an interface meeting the user’s needs, the job of the technical communicator becomes much easier.
We no longer must fix a poor interface with documentation. Instead, we are create documentation the helps the user solve real-world problems by putting the right information in the right place at the right time in the right format. To put this in different terms: give users exactly what they need, when they need it—no more, no less. In this article, I discuss some points we must consider to decide how to provide the right information at the right time.
What must we do?
The design of software and its accompanying documentation must be reconceived so that the design is done from the problem-solver’s point of view. People are faced with many complexities and obstacles in performing a job and have developed many different strategies in overcoming these obstacles. We must acknowledge these obstacles and strategies and create documentation that minimizes them. Most of the current documentation that I see ignores these obstacles and strategies. Rather than address complex problems, current documents center on routine tasks; each menu option of the program exists in its own world, never connecting to any other option.
This is task-oriented documentation from the program’s point of view, not the user’s point of view.
The differences arise from how programmers and users view software. The programmer, viewing the software with an inside-out perspective works with a bottom-up method and sees a set of disjoint screens that interact according to the program specification. The user, on the other hand, works with a top-down problem solving method and views the software with an outside-in perspective, brings to the program a conceptual schema of how it works. When these two views are excessively out of sync, the program and documentation fail to be usable.
One of our most important jobs as technical communicators is to ensure these views don’t get out of sync. We must become, in Bowie’s words, “information engineers”. An important consideration of information engineering is to take a good look at the application. You need to determine and answer the questions going through the user’s mind while using the software. Carroll et al. found that people already understand the task-relevant concepts of the program. It is because of this understanding on the user’s part that we should strive to create designs that directly address user tasks in user terms. Users already know what they want to do, it is our responsibility to ensure they can easily accomplish it.
Techniques for good information engineering
Start with the User at the Beginning: It falls upon the technical communicator to help ensure the user is represented during product design. (Getting the technical communicator represented during design is another story.) Apply the user’s complex problems against the system design requirements to gain an understanding of how to support the relationship between them. When you decide what to write on a process, decide which parts of the process are really needed. As a result, you define which parts really need documentation. Otherwise, you are only doing outlining and doing neither audience analysis nor task analysis. As Spyridakis and Wenger state, everything must be considered: “We carefully consider our intended reader’s knowledge, experience, situation, and culture; we then seek to match the style, content, and design of a document to the tasks, needs, and desires of various readers” (13, p.202).
Answer the User’s Real Questions: Complex tasks involve more than single program options or tasks; they involve the real questions asked by the user. A simple task involves a single menu option and most current documentation posses it in terms of the program (Using the xxx function). A complex task is the complete piece of the big action. The complex task typically involves a question posed in terms of the user’s job and requires the use of several menu options. People sitting before a computer program don’t ask “how do I use this Frame option?’ they ask “is there anyway to get this block of stuff over there?’ As such, answering the user’s real questions means creating documentation using user terminology and containing procedures using multiple menu options.
Consequently, the documentation will not fit neatly into the software organization. However, this will be truly task-oriented from the user’s point of view and will allow the user to quickly find the necessary information. Do not be afraid of overlapping information. The same procedure or concept may appear in multiple places. In a highly integrated business environment, answering the question may even require using more than one program. The common design method of defining and considering each menu option as independent of all other functions does not and never will answer a real-world question.
Optimize Documentation as a Single Unit: The move toward single source documentation, with the same text appearing on paper and in online help, while helpful to us as writers, may not be useful to the user. If our goal is putting the right information in the right place at the right time in the right format, then we must consider exactly what we are putting in each place. No one seems to argue that paper manuals, online context sensitive help, and online reference each perform a different job and is used in a different way. Yet, they often each describe everything, instead of concentrating on what they do best. Think about the strengths of each and how they can help solve the user’s complex questions, then decide where to address that question and only place what is needed to solve that question in that section. In other words, globally optimize across everything the user sees instead of optimizing each part individually.
Remember that Users Make Mistakes: Most computer users want to get on the machine and use it to solve a real task right away. They do not want to spend time learning how to use the program. By doing so, the users will make mistakes. The documentation must address how to fix those errors.
Writers need to concentrate their task analyses more on likely errors that users may commit. Task analyses, therefore, should depart from an error-free perspective and instead focus on task complications and strategic responses, that is, on the inevitability of committing errors and ways of getting out of them. (9, p. 220)
Accept that errors happen and design efficient ways of correcting them from the beginning. (Think of how many times you referred to the documentation because something wasn’t working right and all it told you was to push the button you had pushed.) As the users become more familiar with the system, they rely more on memory and the number of mistakes may actually increase, although they accomplish the task quicker. (7,5)
When you start thinking about error correction in overall design, the flavor of the documentation changes. Rather than only containing error-free procedures, it addresses error correction; good documents address the procedure’s limitations and its common mistakes.
How the Information is Presented Matters:Information presentation has major effects on people’s decisions; depending on the presentation, they may actually make opposite choices and believe them to be best (14,6). Thus, presentation of information becomes the crucial factor in maintaining the flow of information (8). When people look at information, they tend to see what they expect to see. Unfortunately, getting them to see what we want them to see is often complicated by concepts of how a previous program worked. Duin claims that documentation “that is poorly organized will not elicit the appropriate schemata from the reader’s mind.” As a result, the reader voices the commonplace complaint about unusable documentation.
Also, the presentation format can actually change the way users use the information. Slavic found that users tend to change their assessment strategy to fit to the presentation method, rather than transform the information to fit a better assessment strategy. Thus, changes that make it easier to process information also increase the information’s impact. Problems occur when minor, but easy to present information, occupies too much of the design and, diminishes the salience of important, but harder to present, information.
Remember, the Interface also Communicates:Inconsistent design can significantly reduce a user’s perception of the intuitiveness of the software. This forces users to focus on relearning how to accomplish the task, rather than concentrating on the task itself. Remember that a user interface has two logical parts. The first, the physical interface with the buttons, windows, etc., is by far the easiest. How to design this part of the interface is the focus of books on user interface design. The second part of the user interface is the content. This is the content, use, order and actual text of labels on the entry fields (as opposed to the placement/font), the error messages, and the help text. It also includes the larger view of the interrelation of screens and components of the program.
Helping users solve real-world problems means focusing everything the use sees on the user problem and not on the easiest way to program/write it. Programmers often concentrate only on the interface layout. That part is easy and they have set guidelines. But a consistent user interface is not sufficient to make a program usable.
The interface layout and content must be combined and the failure of either reduces the overall effectiveness of the program. It also causes excessive amounts of documentation, either online or, most likely, paper to be generated in an attempt to fix the problem.
When everything communicates effectively
With the wide spread use of Microsoft® Windows®, the interface of the PC user has become much more consistent. However, the content of the program and documentation still varies from program to program. As such, while users understand how to point and click in the program, they still don’t know what to point and click or what to put in the blanks. One measure of successful communication is having users finish the interaction and feel they have smoothly completed their task. Feelings of having finally squeezed the results out of the system or of inferiority because they had to ask other people should not occur. To maximize user productivity we must break with the current writing methodology of addressing each menu option separately and address complex problems. Our documentation must provide the methods for accomplishing the complex tasks and provide answers to the real questions users ask.
We must go beyond simple procedures and create documents which assist in solving complex problems.
Michael J. Albers, http://www.stcsig.org/usability/newsletter/0505-effectivedocs.html
“The ability to create effective verbal and visual information for people to use according to their own needs is at the heart of the communicator’s role.” (12, p.38) Here lies the holy grail of effective software documentation. However, as long as the developer sees software as a series of screens with fields optimized to access a database, as long as the technical communicator sees it as a series of screens to be described field by field as long as senior management sees it as a series of reports that they needed yesterday for answers they need today, as long as IS management sees it as a steadily decreasing budget item, as long as users see it as something new they’ll have learn and something which may cost them their jobs, the holy grail will remain hidden in the mists.
We need to stop considering documentation, software interface, and online help, as separate entities and remember we are communicating with users. We must go beyond simple instructions and design documents that assist in solving real-world complex problems. We need to support the problem-solving strategies that address the user’s real tasks. Documentation for complex tasks means thinking big; it means considering and integrating everything the user sees: user interface, online help, error messages, and paper manuals. To accomplish this goal, we must do more than think about a program’s menu structure; instead, we must follow a different path.
Documentation researchers need to discover the conditions and real workplace tasks that require a user to consult a manual to make up for a poor interface and require document designers to become involved in interface development, online help design, or organizational training. (10, p.83).
To successfully communicate to users, documentation must do more than meet the user’s information needs, it must present the information in the same way the user processes the information. We can change appearances, but effective communication does not lie in appearances. Communication works at the level of assumptions, implications, and expectations. Effective communication means determining and providing answers to the complex problems of the real-world. Analysis should be stated “in terms of the behavior-shaping goals and constraints that define the boundaries of a space guided by their local and subjective performance criteria” (11). Dobin insists that to support problem solving for open-ended problems we must gain an in-depth understanding of the user and not the software. “The user’s vocabulary, the user’s reasons for looking things up, and the problems the user confronts must be clearly anticipated’ (3, p.89). Actually, if we define the conditions and real workplace tasks early in the project and then use that information to design an interface meeting the user’s needs, the job of the technical communicator becomes much easier.
We no longer must fix a poor interface with documentation. Instead, we are create documentation the helps the user solve real-world problems by putting the right information in the right place at the right time in the right format. To put this in different terms: give users exactly what they need, when they need it—no more, no less. In this article, I discuss some points we must consider to decide how to provide the right information at the right time.
What must we do?
The design of software and its accompanying documentation must be reconceived so that the design is done from the problem-solver’s point of view. People are faced with many complexities and obstacles in performing a job and have developed many different strategies in overcoming these obstacles. We must acknowledge these obstacles and strategies and create documentation that minimizes them. Most of the current documentation that I see ignores these obstacles and strategies. Rather than address complex problems, current documents center on routine tasks; each menu option of the program exists in its own world, never connecting to any other option.
This is task-oriented documentation from the program’s point of view, not the user’s point of view.
The differences arise from how programmers and users view software. The programmer, viewing the software with an inside-out perspective works with a bottom-up method and sees a set of disjoint screens that interact according to the program specification. The user, on the other hand, works with a top-down problem solving method and views the software with an outside-in perspective, brings to the program a conceptual schema of how it works. When these two views are excessively out of sync, the program and documentation fail to be usable.
One of our most important jobs as technical communicators is to ensure these views don’t get out of sync. We must become, in Bowie’s words, “information engineers”. An important consideration of information engineering is to take a good look at the application. You need to determine and answer the questions going through the user’s mind while using the software. Carroll et al. found that people already understand the task-relevant concepts of the program. It is because of this understanding on the user’s part that we should strive to create designs that directly address user tasks in user terms. Users already know what they want to do, it is our responsibility to ensure they can easily accomplish it.
Techniques for good information engineering
Start with the User at the Beginning: It falls upon the technical communicator to help ensure the user is represented during product design. (Getting the technical communicator represented during design is another story.) Apply the user’s complex problems against the system design requirements to gain an understanding of how to support the relationship between them. When you decide what to write on a process, decide which parts of the process are really needed. As a result, you define which parts really need documentation. Otherwise, you are only doing outlining and doing neither audience analysis nor task analysis. As Spyridakis and Wenger state, everything must be considered: “We carefully consider our intended reader’s knowledge, experience, situation, and culture; we then seek to match the style, content, and design of a document to the tasks, needs, and desires of various readers” (13, p.202).
Answer the User’s Real Questions: Complex tasks involve more than single program options or tasks; they involve the real questions asked by the user. A simple task involves a single menu option and most current documentation posses it in terms of the program (Using the xxx function). A complex task is the complete piece of the big action. The complex task typically involves a question posed in terms of the user’s job and requires the use of several menu options. People sitting before a computer program don’t ask “how do I use this Frame option?’ they ask “is there anyway to get this block of stuff over there?’ As such, answering the user’s real questions means creating documentation using user terminology and containing procedures using multiple menu options.
Consequently, the documentation will not fit neatly into the software organization. However, this will be truly task-oriented from the user’s point of view and will allow the user to quickly find the necessary information. Do not be afraid of overlapping information. The same procedure or concept may appear in multiple places. In a highly integrated business environment, answering the question may even require using more than one program. The common design method of defining and considering each menu option as independent of all other functions does not and never will answer a real-world question.
Optimize Documentation as a Single Unit: The move toward single source documentation, with the same text appearing on paper and in online help, while helpful to us as writers, may not be useful to the user. If our goal is putting the right information in the right place at the right time in the right format, then we must consider exactly what we are putting in each place. No one seems to argue that paper manuals, online context sensitive help, and online reference each perform a different job and is used in a different way. Yet, they often each describe everything, instead of concentrating on what they do best. Think about the strengths of each and how they can help solve the user’s complex questions, then decide where to address that question and only place what is needed to solve that question in that section. In other words, globally optimize across everything the user sees instead of optimizing each part individually.
Remember that Users Make Mistakes: Most computer users want to get on the machine and use it to solve a real task right away. They do not want to spend time learning how to use the program. By doing so, the users will make mistakes. The documentation must address how to fix those errors.
Writers need to concentrate their task analyses more on likely errors that users may commit. Task analyses, therefore, should depart from an error-free perspective and instead focus on task complications and strategic responses, that is, on the inevitability of committing errors and ways of getting out of them. (9, p. 220)
Accept that errors happen and design efficient ways of correcting them from the beginning. (Think of how many times you referred to the documentation because something wasn’t working right and all it told you was to push the button you had pushed.) As the users become more familiar with the system, they rely more on memory and the number of mistakes may actually increase, although they accomplish the task quicker. (7,5)
When you start thinking about error correction in overall design, the flavor of the documentation changes. Rather than only containing error-free procedures, it addresses error correction; good documents address the procedure’s limitations and its common mistakes.
How the Information is Presented Matters:Information presentation has major effects on people’s decisions; depending on the presentation, they may actually make opposite choices and believe them to be best (14,6). Thus, presentation of information becomes the crucial factor in maintaining the flow of information (8). When people look at information, they tend to see what they expect to see. Unfortunately, getting them to see what we want them to see is often complicated by concepts of how a previous program worked. Duin claims that documentation “that is poorly organized will not elicit the appropriate schemata from the reader’s mind.” As a result, the reader voices the commonplace complaint about unusable documentation.
Also, the presentation format can actually change the way users use the information. Slavic found that users tend to change their assessment strategy to fit to the presentation method, rather than transform the information to fit a better assessment strategy. Thus, changes that make it easier to process information also increase the information’s impact. Problems occur when minor, but easy to present information, occupies too much of the design and, diminishes the salience of important, but harder to present, information.
Remember, the Interface also Communicates:Inconsistent design can significantly reduce a user’s perception of the intuitiveness of the software. This forces users to focus on relearning how to accomplish the task, rather than concentrating on the task itself. Remember that a user interface has two logical parts. The first, the physical interface with the buttons, windows, etc., is by far the easiest. How to design this part of the interface is the focus of books on user interface design. The second part of the user interface is the content. This is the content, use, order and actual text of labels on the entry fields (as opposed to the placement/font), the error messages, and the help text. It also includes the larger view of the interrelation of screens and components of the program.
Helping users solve real-world problems means focusing everything the use sees on the user problem and not on the easiest way to program/write it. Programmers often concentrate only on the interface layout. That part is easy and they have set guidelines. But a consistent user interface is not sufficient to make a program usable.
The interface layout and content must be combined and the failure of either reduces the overall effectiveness of the program. It also causes excessive amounts of documentation, either online or, most likely, paper to be generated in an attempt to fix the problem.
When everything communicates effectively
With the wide spread use of Microsoft® Windows®, the interface of the PC user has become much more consistent. However, the content of the program and documentation still varies from program to program. As such, while users understand how to point and click in the program, they still don’t know what to point and click or what to put in the blanks. One measure of successful communication is having users finish the interaction and feel they have smoothly completed their task. Feelings of having finally squeezed the results out of the system or of inferiority because they had to ask other people should not occur. To maximize user productivity we must break with the current writing methodology of addressing each menu option separately and address complex problems. Our documentation must provide the methods for accomplishing the complex tasks and provide answers to the real questions users ask.
We must go beyond simple procedures and create documents which assist in solving complex problems.
Michael J. Albers, http://www.stcsig.org/usability/newsletter/0505-effectivedocs.html
posted by waqas at
9:37 PM
|
1 comments
