Developing Quality Technical Information Ch03 Accuracy

47 Chapter3 Accuracy Be sure you are right, then go ahead. —David Crockett As a writer of technical information, you have an important responsibility: to provide information that is accurate and free of errors. Users depend on you for that accuracy; they stake their time and money on it. Achieving accuracy in technical information is to a writer as finding the bull’s-eye of a target is to an archer; it is an all-important goal, albeit a goal that isn’t always easy to achieve. For technical information to be accurate, every piece of information must be accurate, including conceptual information, factual statements, procedures, graphical elements, and other details in the writing. Inaccuracies might or might not be obvious. Those that aren’t obvious are often more significant, because the user might take action based on inaccu- rate information. For example, imagine someone leaving a message on your answering machine with directions to “turn right at the dead end.” Before you get in your car, you know that this is incorrect because you can’t turn right at a dead end. Therefore you take steps to resolve the inaccuracy, like looking at a map or asking for clarification. 48 Developing Quality Technical Information Easy to use If the person’s message says “turn right at Front Street and go straight until you cross the railroad tracks,” you could drive for quite some time before realizing that no railroad tracks are in this direction, and that you were actu- ally supposed to turn left instead of right. You’ll probably be more upset by the second set of directions than the first. In the article “Docs in the Real World,” Carolyn Snyder and Jared Spool rec- ognize the vital importance of information accuracy when they coin the term “trust-breakers.” These are errors in information that cause users to avoid the information because they don't trust it. Snyder and Spool make several observations about the effects of inaccuracies on users: � Even small inaccuracies damage the confidence of some users, espe- cially those users who don't know how to work around the problem. When they discover an error, they tend to give up on the information and call the help desk. � The information often takes the blame for inaccuracies in the underlying product or in related products. Users don't care whose fault an error is; they are simply less willing to use the information in the future. � After experiencing major problems in information, users are less likely to give the information another try, even in future releases. Regardless of how much time users take to detect an inaccuracy, their confi- dence in the information is eroded; they might even choose not to use the information or the product at all. To make information accurate, follow these guidelines: � Write information only when you understand it, and then verify it. � Keep up with technical changes. � Maintain consistency of all information about a subject. � Use tools that automate checking for accuracy. � Check the accuracy of references to related information. 49 Accuracy Write information only when you understand it, and then verify it By the time you publish information, you must understand the subject well enough that you can tell users what they need to know. Sometimes you can understand the subject quickly and be able to write about it accurately and clearly without much difficulty. At other times, the subject is new and not well documented. Perhaps a software product is not available for you to try, or technical experts are unable to explain the subject to you at the beginning of the writ- ing cycle. When you can’t get first-hand experience with a product or can’t get help from technical experts, you must start with what you do under- stand to write your first draft. Consider including questions to the experts in your early drafts to solicit the explanations that you need to fine-tune the information for users. Technical experts are sometimes better at reviewing something that is written and identifying the inaccuracies than they are at documenting a technical subject from scratch. Write the information and have it reviewed as many times as necessary to ensure that it is accurate by the time when you publish the information. Although you do need to understand the technical subject that you write about, you don’t need to understand it as well as the developers. In fact, if you understand the internal workings of the product too well, you run the risk of including more information than users need. (Chapter 4, “Complete- ness,” on page 75 provides guidelines for knowing how much information is needed.) If you understand what you’re writing about, you’ll be better able to explain concepts and define terms, as in the following explanation of a wide area network: Original Revision A wide area network (WAN) is a network that encompasses a wide area. A wide area network (WAN) is a computer network that encompasses a large geographical area. A WAN usually includes two or more local-area networks (LANs). 50 Developing Quality Technical Information Easy to use In the original passage, the writer does not yet understand the concept of a WAN, and the resulting definition is too simplistic to be helpful to most users. Perhaps the original passage is a first attempt at writing the defini- tion. After seeking a technical review, the writer is able to improve the accu- racy of the definition as shown in the revised passage. When you write procedures, you need to understand how users are likely to use the procedures to perform relevant tasks. If you don’t understand how users perform the task, the task orientation of the information will suffer, and you might also end up with an inaccurate procedure. For example, you might obtain a general outline of the procedure from a developer who is not thinking about how users will use the procedure. The following topic shows a procedure on the Web that does not satisfy all users: The original procedure has several problems: � The first paragraph states that the fixes are available on the Service Web page but does not instruct the user to follow the link. Many users focus on the actual procedure and might never follow the link to the Service Web page. Original Location: http://www.dqti.InfoDBase.com F E V G B O W Hile dit iew o ookmarks ptions indow elp My Web Browser When the InfoDBase product changes between releases, you can install these fixes from the Web. The currently available fixes are listed at the To download and install fixes from the Web, follow this procedure: 1. Download the appropriate .zip file into a temporary directory by clicking the file name. The valid file names for Release 5 are: , , , and 2. In a command prompt window, change to the directory where you store the InfoDBase code. 3. Issue the following command, where is the name of the fix that you want to install: install .zip A message informs you when the installation process has finished. InfoDBase Service page fix5file1.zip fix5file2.zip fix5file3.zip fix5file4.zip fix5file5.zip fix5file6.zip . , , . fixfilename fixfilename fixfilename 51 Accuracy � Step 1 specifies the names of the fix files. The writer, perhaps with good intention, lets users double-click the file names directly, even though this list is for only one release. Users of other releases cannot accomplish the task of downloading fixes by using this procedure. � The download list in step 1 is likely to become out of date if the writer doesn’t update the procedure each time that a new fix becomes avail- able. The revised procedure accurately takes into account how users will install fixes. Step 1 instructs the user to go to the Service Web page to identify the appropriate fixes and to download and install them. The revised procedure does not mention specific file names and is therefore less likely to become outdated. The best way to understand a technical subject that you are writing about is to use the product as a user would. The more that you, as a writer, can use a product, tool, or interface, the more responsible you can be for the accuracy of the information. For example, when you write a procedure for creating a database view that is based on two tables, you can use the interface to decide what steps to include. Then, after you finish writing the procedure, you can test it; if you successfully create the view, you know that the proce- dure is accurate. Revision Location: http://www.dqti.InfoDBase.com F E V G B O W Hile dit iew o ookmarks ptions indow elp My Web Browser When the InfoDBase product changes between releases, you can install these fixes from the Web. To download and install fixes from the Web, follow this procedure: 2. For each fix that you want to install, select the file name of the fix (in the format .zip), and click the button to store the fix in a temporary directory. 3. In a command prompt window, change to the directory where you store the InfoDBase code. install .zip A message informs you when the installation process has finished. 1. Go to the current list of fixes (at the ). Find the section of the list that relates to your release of InfoDBase, and which fixes you want to install. 4. Issue the following command, where is the name of the fix file that you want to install: InfoDBase Service page fixfilename fixfilename Install fixfilename read the descriptions to determine 52 Developing Quality Technical Information Easy to use When time and circumstances allow, try to ensure the accuracy of your information in one or more of the following ways: � Schedule an informal usability walkthrough in which you and other writers use the information to perform some or all of the important user tasks. � Observe a formal usability walkthrough, in which actual users do cer- tain tasks with the information and associated product, tool, or inter- face. � Visit one or more of the users of your information to observe them as they do their day-to-day tasks. These kinds of activities increase your knowledge of how your users do their jobs so that you can develop accurate information that makes their jobs easier. Even writers who use the product, tool, or interface extensively and partici- pate in walkthrough activities must also seek feedback from others: � Technical reviewers review and validate the accuracy of technical infor- mation. � The writing team reviews and validates the accuracy of nontechnical information such as boilerplate text. You can solicit this feedback informally, while you write small parts of your information, as well as formally, when you hold reviews or inspections. Before writing technical information, make sure that you understand the subject well enough so that you can explain to users what they need to know. Whenever possible, use the product, tool, or interface as you are developing the information, and always validate the accuracy before deliv- ering the information to users. 53 Accuracy Keep up with technical changes Technical information that is not current is inaccurate. Information can become outdated from one release to the next or within a development cycle. Each time that you publish a new edition of your information, ensure that trademarks, product names and release levels, and boilerplate information are current. Try to avoid mentioning specific release levels of products unless you have a valid technical reason to do so, as in the following cases: � Marketing information that highlights the features of a new release or version of a product � Restrictions that apply to a specific release In a 2002 commentary about Producing Quality Technical Information, the hand- book on which this book was based, Theo Mandel compares a Web site to a gar- den. He says, “You must pull weeds and replace plants and flowers on a timely basis or the garden will not attract and interest its viewers.” Although Web information is especially prone to becoming outdated, the garden analogy works well for all types of technical information that you develop. If you take the time to plan and plant a garden, don’t you also take the time to water it, fertilize it, and pull weeds from it? Technical information can become outdated and inaccurate just as a garden can wither and become overgrown with weeds due to the lack of attention. Just as a good gardener replaces flowers and plants and pulls weeds, you need to occasionally replace information that was once but is no longer valid with new information. The following Web page provides general information about the InfoDBase product: Original Using InfoDBase SQL tables and SQL views InfoDBase Version 1.1 provides support for accessing data in SQL tables and SQL views.You can access data in the following ways: Look at and change data! ! ! ! Create reports and charts Delete SQL tables and SQL views Print SQL tables and SQL views Location: http://www.dqti.InfoDBase.com F E V G B O W Hile dit iew o ookmarks ptions indow elp My Web Browser 54 Developing Quality Technical Information Easy to use Specifying the release number for a product, as the original Web page does, might be accurate for this release, but the release number could look inaccu- rate if it’s not changed in the next release. If a statement about a product will continue to be true in future releases, write the statement in a general way, as in the revised Web page. Information can also become outdated during the development cycle for a product, even before it is available. For example, when a specifications doc- ument is available, writers need to incorporate information from it. However, this document can get out of sync with the actual product, even if the team records changes in the design. Changes creep in, and people forget to mention them. Ensure that your own information accurately describes the product by checking that the information matches what users will see and experience. Accuracy problems can result when you include graphics that show all or part of the user interface if the interface changes after the information is finalized. The visual effectiveness guideline “Avoid illustrating what is already visible” on page 280 discourages inclusion of interface elements except when doing so is necessary for users to complete a task. Assume that a writer determines that the following menu needs to be included in the information and that the writer relies solely on the technical specification: Revision Location: http://www.dqti.InfoDBase.com F E V G B O W Hile dit iew o ookmarks ptions indow elp My Web Browser Using InfoDBase SQL tables and SQL views InfoDBase provides support for accessing data in SQL tables and SQL views.You can access data in the following ways: ! Look at and change data Create reports and charts Delete SQL tables and SQL views Print SQL tables and SQL view ! ! ! 55 Accuracy Suppose that the specification that the writer relies on includes the original menu, with the Fast Forward and Rewind choices in that sequence. The developer, however, decides to change the sequence of the menu items without informing the writing team. The original menu that the writer includes is now inaccurate. In this case, the revised menu actually matches the interface. A writer who assumes that the specification is correct and includes the original menu in information for users inadvertently introduces an accuracy problem. A writer who checks the actual menu can detect the error and correct the menu in the user information, as shown in the revised menu. Original Play/Pause Stop Skip Back Skip Forward Preview Go To. . . Language Volume Fast Forward Rewind Space Period Page Up Page Down Ctrl+V Ctrl+G Ctrl+Right Ctrl+Left Revision Play/Pause Stop Skip Back Skip Forward Rewind Preview Go To. . . Language Volume Fast Forward Space Period Page Up Page Down Ctrl+V Ctrl+G Ctrl+Left Ctrl+Right 56 Developing Quality Technical Information Easy to use As more and more technical information is delivered on the Web, the chal- lenge to keep that information current is even greater than it is for printed information. Users of the Web expect that the information that they see is current because they know that the Web can be updated at any time. As a result, users are much less inclined to tolerate out-of-date information on the Web than in print. If you deliver technical information to users on the Web, you can satisfy users’ needs for information currency and accuracy by following these tips: � Set a regular update schedule and follow it. Identify a qualified backup writer to handle updates when you are unavailable. � Indicate the date and time of the last update for the Web page so that users know how current the information is. � Post the schedule for updates on the Web page, if possible, so that users know when the information will next be updated. � Include a feedback mechanism on the Web page so that users can com- municate problems to you. Handle this feedback in a timely manner. Suppose that a user views the following Web page in the end of March 2003: By viewing this original Web page, the user cannot determine whether the information is current. Original Location: http://www.dqti.InfoDBase.com F E V G B O W Hile dit iew o ookmarks ptions indow elp My Web Browser To download a product fix or enhancement, click the name of the module below, and click to download it into the appropriate directory. � � � � Fixes a known problem in startup processing Enhances the parameter definition process Enhances print-on-demand capabilities Fixes a known problem in advanced mathematical calculations Save As MOD0126 MOD0303 MOD0524 MOD0806 57 Accuracy In the original Web page, the list is incomplete, but the user has no way of knowing this. No update schedule is posted, no last-updated date is pro- vided, and no feedback mechanism is available. Users of the revised Web page, however, can trust the currency and accuracy of the information to a much greater degree because of the inclusion of these features. Regardless of whether information is on the Web or in other formats, techni- cal information that is not current is not accurate. Therefore, include only information that is current, avoid including information that is likely to become quickly outdated, and validate the currency of existing information. Revision Location: http://www.dqti.InfoDBase.com F E V G B O W Hile dit iew o ookmarks ptions indow elp My Web Browser To download a product fix or enhancement, click the name of the module below, and click to download it into the appropriate directory.Save As Fixes a known problem in startup processing 2002-12-03 09:12:02 EST Enhances the parameter definition process 2002-12-17 12:31:45 EST Enhances print-on-demand capabilities 2003-01-07 09:30:00 EST Fixes a known problem in advanced mathematical calculations 2003-02-04 16:12:57 EST Fixes a known locking problem 2003-03-04 08:51:05 EST Fixes a known problem in shutdown processing 2003-03-18 09:30:00 EST Update schedule: First and third Tuesday of each month, or the first business day thereafter. Last updated: 2003-03-18 09:30:00 EST MOD0126 MOD0303 MOD0524 MOD0806 MOD0902 MOD1216 Feedback 58 Developing Quality Technical Information Easy to use Maintain consistency of all information about a subject Many accuracy problems occur because the writer updates information in one place but not in other places where it appears. Faced with inconsistent information, the user doesn’t know which information is correct. When you determine that certain information needs to be repeated word for word, you can take advantage of the best way to ensure information consis- tency: r