Documentation design

Documentation design

70.1 Purpose

Documentation consists of the specifications, instructions, tutorials, reference guides, and similar materials that accompany and explain a piece of software or a hardware component. Documentation serves as a communication vehicle, provides a useful reference, and facilitates management’s control of the system development process and of system operation. This chapter briefly discusses documentation types and documentation contents and offers several tips for producing good documentation.

70.2 Strengths, weaknesses, and limitations

Documentation serves as a communication vehicle, provides a useful (testing, debugging, maintenance, and operational) reference, enhances productivity, supports user training, and promotes continuity and consistency. Additionally, it facilitates management’s control of the system development process and of system operation. Other information system development projects can sometimes borrow components and/or ideas from (or reuse) existing documentation. Details concerning modifications to and versions of an information system are important system validation criteria.

On the negative side, creating and maintaining effective documentation is expensive. However, the benefits almost always outweigh the cost.

70.3 Inputs and related ideas

Documentation is created throughout the system development life cycle. Good documentation is essential during the testing, implementation, and maintenance stages (Parts VII and VIII).

Many of the tools and techniques discussed in this book can be used to generate charts, diagrams, narratives, and other forms of documentation. In particular, see screen and forms design (Chapter 46), report design (Chapter 47), user interface design (Chapter 48), dialogues (Chapter 49), windows design (Chapter 50), web page design (Chapter 51), logic flowcharts (Chapter 55), decision trees (Chapter 57), decision tables (Chapter 58), and HIPO (Chapter 64). A technical inspection (Chapter 23) is an excellent tool for evaluating the quality of the documentation.

70.4 Concepts

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.

70.4.1 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, system 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.

70.4.2 Documentation contents

The precise content of a unit of documentation depends on its intended use. For example, a source code listing might be appropriate for a maintenance 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.

70.4.3 Documentation tips

Listed below are several tips for creating effective documentation.

70.4.3.1 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 understand 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.

70.4.3.2 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.

70.4.3.3 Design for easy reference

People rarely read documentation from cover to cover. Instead, they use such features as a table of contents, an index, thumb tabs, or a search 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 everyone 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.

70.4.3.4 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.

70.4.3.5 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, multimedia, 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.

70.4.3.6 Concurrently develop the documentation and the system

Generally, the documentation and the system should be developed concurrently, 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.

70.4.3.7 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.

70.4.3.8 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.

70.4.3.9 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.

70.5 Key terms

Command-oriented documentation —: Documentation that contains all the commands used by the system and/or the program, usually arranged in alphabetical order.
Diagnosis-oriented documentation —: Documentation that describes the type and the nature of warning messages and error messages and explains the causes of and solutions for each error.
Documentation —: The specifications, instructions, tutorials, reference guides, and similar materials that accompany and explain a piece of software or a hardware component.
Execution-oriented documentation (application based documentation) —: Documentation designed to support an application.
External documentation —: Documentation that is kept at the user’s location (or some other remote site) and is designed primarily for the user.
Internal documentation —: Specifications, records, and manuals that are stored, maintained, and used by technical professionals.
Operation-oriented documentation —: Command-oriented documentation that groups commands based on the nature of the operation.

70.6 Software

CASE software is particularly useful for developing analysis and design documentation. Word processing, graphics, and desktop publishing software are also useful. Additionally, many of the tools and techniques discussed in this book produce charts, diagrams, and other materials that can serve as documentation.

70.7 References

1. Birrell, N. D. and Ould, M. A., A Practical Handbook for Software Development, Cambridge University Press, Cambridge, U.K., 1986.

2. Hannan, J., Ed., A Practical Guide to Data Processing Management, Auerbach Publishers, New York, 1982.

3. Hannan, J., A Practical Guide to EDP Auditing, Auerbach Publishers, New York, 1982.

4. Hastings, G. P. and King, K. J., Creating Effective Documentation for Computer Programs,Prentice-Hall, Englewood Cliffs, NJ, 1986.

5. Katzin, E., How to Write a Really Good User’s Manual, Van Nostrand Reinhold, New York, 1985.

6. Saldarini, R. A., Analysis and Design of Business Information Systems, Macmillan, New York, 1989.

7. Singer, L. M., Written Communications for MIS/DP Professionals, Macmillan, New York, 1986.

Search This Blog

information systems course