The quality of an information system depends not only on such attributes as flexibility, user-friendliness, reliability and performance, but also on the quality of the documentation. In fact, to the user, the documentation and the user interface are the system.
Documentation consists of the specifications, instructions, tutorials, reference guides, and similar materials that accompany and explain a piece of software or a hardware component. Good documentation is complete, clear, understandable, current, and reusable.
Documentation types
Internal documentation consists of specifications, records, and manuals that are stored, maintained, and used by technical professionals. (It is “internal” because it is kept within the technical facility.) Examples include system documentation, program documentation, operations manuals, command manuals, input/output specifications, interface specifications and descriptions, sample input/output records and forms, system analysis documentation, sys- tem design documentation, and related data descriptions and specifications. External documentation, in contrast, is kept at the user 's location (or some other remote site) and is designed primarily for the user. Examples include user manuals, execution guides, error manuals, assistance manuals, guidelines, operating procedures, and so on.
Command-oriented documentation contains all the commands used by the system and/or the program, usually arranged in alphabetical order. Typically, the syntax, options, formats, attributes, and one or more examples are listed for each command. Operation-oriented documentation groups commands based on the nature of the operation. For example, commands might be grouped into such categories as file, edit, help, tools, and format. Execution-oriented (or application-based) documentation is designed to support an application. Typically, such details as operating procedures, execution sequence, the rules and privileges associated with accessing a file, and various restrictions associated with the system are documented. On-line help is an example of execution-oriented documentation. Diagnosis- oriented documentation describes the type and the nature of warning messages and error messages and explains the causes of and solutions for each error. Generally, the systems manual is a combination of command-oriented and diagnosis-oriented documentation. The user manual is often a combination of execution-oriented and operation-oriented documentation. It is also possible to classify documentation by system development life cycle phase. Requests for proposal (RFP), requests for quotation (RFQ), the requirements specification, various process and data analysis models, and the feasibility study report are examples of analysis documentation. Data flow diagrams, the data dictionary, and other types of data and design specifications are examples of design documentation. Change reports, version control specifications, the system manual, the user manual, and similar manuals and specification are examples of maintenance documentation.
programmer, but the end user of that program will need a clear explanation of exactly how to work with the user interface. Form affects content, too; printed documentation and on-line documentation are inherently different. Documentation is prepared for future reference, so most documentation contains a table of contents and/or an index that makes it easy to find key topics. For example, many on-line help features include a help contents window , an index, and a search facility.
Often, one of the first pages or screens in the documentation is an introduction that explains the purpose of the documentation, identifies the intended audience, and identifies the people responsible for creating the documentation and for answering questions about the documentation. A glossary is often included, too. With the growing acceptance of the Internet and the World Wide Web, some on-line documentation packages now feature key words hyperlinked to a glossary entry.
The detailed contents of the documentation can take many different forms, from pure narrative, to graphics, to interactive dialogue, to hybrid multimedia presentations. Functional narratives are common. For example, a user manual might feature a series of annotated user interface screens with explanations, or an annotated sample report. Play script style features two (or more) columns, with key actions listed in the left column and the associated explanation listed in the right column. See the chapters listed under Inputs and Related Ideas for other tools that might be used to prepare documentation.
Documentation tips
Listed below are several tips for creating effective documentation .
Write for the user
A basic principle of any kind of writing is to write for the intended audience. Effective documentation begins with a thorough understanding of the user, the user 's needs, and the user 's technical expertise. Analysis-oriented documentation should be written for the analyst. Detailed program documentation should be written for the programmer. The user manual should be written for the end user.
The principle seems obvious, but it is frequently ignored. All too often, documentation is prepared by technical personnel who either do not under- stand the user, do not care about the user, or care more about impressing their technical peers than communicating effectively with the user. Documentation that is not written for the intended reader will not be used. Unused documentation is a waste of time and effort.
One final point: Many sources cite ease of use as a primary documentation criterion. Ease of use is a relative concept. The only valid basis for measuring ease of use is the intended user.
Never leave the user hanging
Good documentation never leaves the user hanging. All explanations should be written in user terms, using words the user understands. Technical terms should be clearly defined in context or in a glossary. The use of acronyms should be kept to a minimum. When an acronym is used, its meaning should be spelled out on each page where it appears.
Design for easy reference
People ra r ely r ead documentation f r om cover to cove r . Instead, they use such featu r es as a table of contents, an index, thumb tabs, or a sea r ch tool to quickly find a specific answer to a specific question. Effective documentation is designed with such use in mind.
Design the contents to be easy to find. Use a table of contents and/or an index. Put the entries in alphabetical order or group them by function. If the documentation is on line, provide a key word search facility.
Redundancy can be valuable. For example, different users might visualize a document as a page, a form, or a screen. Rather than training every- one to use the same term, it might be better to provide links to the right information from all of those aliases, or from any appropriate starting point. To cite another example, imagine that two topics are closely related. It is unreasonable to assume that a user searching for topic B has previously read topic A, so redundant elements of the explanation should be repeated for both topics.
Not all users need the same amount of detail, so drilldown is another useful principle. For example, each topic might be organized as a pyramid, with general concepts on top, a typical or most likely scenario in the middle, and exceptions or special cases at the bottom. Given such a structure, a given user can “drill down” only as far as necessary to answer his or her question.
Be consistent
Consistency is crucial. Consider, for example, the graphic user interface defined by the World Wide Web. Once a user learns how to access and navigate one site, the same point and click operations work on virtually any site. Similarly, if all the elements in a given documentation package are designed with a consistent look and feel, the user 's training time is greatly reduced. Perhaps the best example of a consistent look and feel is the desktop metaphor defined by the Apple Macintosh and Microsoft Windows. A few basic operations (point, click, drag) are used to manipulate a few basic elements (windows, icons, menus) in virtually every application. Consequently, given a little practice, the basic operations and elements become almost intuitive, so the user can effectively ignore them and focus on the task at hand. Similarly, the physical structure of the documentation should make access almost intuitive, and not get in the user 's way. In fact, because so many people are already familiar with the metaphors, it often makes sense to design the documentation to resemble a Windows or World Wide Web application.
Plan
Good documentation does not just happen; it must be carefully planned. In fact, many software developers view documentation as a discrete phase that is performed concurrently with analysis, design, and implementation, and every organization should (at the very least) have in place a formal documentation process complete with formal procedures and standards. As a minimum, for each unit of documentation, the content, the organizational structure, the sequence of topics, the intended level of detail, the presentation methods and approaches (print, graphics, interactive, multi- media, etc.), and the users' comprehension level must be clearly defined before detailed writing begins. Additionally, a budget, resource allocations(personnel, equipment), quality standards, timing constraints, and approval procedures must be established for the documentation.
Concurrently develop the documentation and the system
Generally, the documentation and the system should be developed con- currently, because if the documentation is viewed as an afterthought, its quality will reflect that point of view. Ideally, the appropriate documentation is a measurable exit criterion from each step in the system development life cycle. In other words, if the documentation is not complete, the step is not complete.
Test
The only way to be sure the documentation is good is to test it. The ultimate purpose of the documentation is to support the user. Consequently, the user 's opinion is the one that counts, and user involvement in the documentation testing process is essential. In some organizations, the technical professionals create the documentation, but technical personnel often lack a user prospective and many consider documentation a waste of time. In other organizations, technical writers, subcontractors, temporary workers, and other support personnel create the documentation, but less-technical people often lack technical understanding. A technical inspection (Chapter 23) is an excellent tool for evaluating the quality of the documentation, particularly if the inspection team includes both technical personnel and users.
Standards are important. Some standards are procedural. Start with a plan, have management and the user approve the plan, and conduct regular inspections to enforce the plan. Other standards can be applied to the content. For example, there are several easily computed readability indexes that can be correlated to the reading level of the intended users.
Get management committed
People do things they are rewarded (financially or emotionally) for doing and they avoid things they are penalized for doing. If management treats documentation as a necessary evil, rewards those who ignore the documentation in order to get the “real” work done, and penalizes those who insist on doing the job “right” in spite of the schedule, then the documentation will not be done properly. Good documentation is produced by organizations that make good documentation a priority.
Learn from what works
Perhaps the best way to improve documentation is to start with documentation that works well, study it carefully to find out why it works, and then use the good documentation as a model.