What is documentation? Criteria for Measuring Usability of Documents

J.E.D.I

1.7 Documentation in the Development Effort

1.7.1 What is documentation? It is a set of documents or informational products to describe a computer system. Each document is designed to perform a particular function such as: • REFERENCE, examples are technical or functional specifications • INSTRUCTIONAL, examples are tutorials, demonstrations, prototypes etc. • MOTIVATIONAL, examples are brochures, demonstrations, prototypes. There are several types of documentation and informational work products. Some of them are listed below: • System Features and Functions • User and Management Summaries • Users Manual • Systems Administration Manuals • Video • Multimedia • Tutorials • Demonstrations • Reference Guide • Quick Reference Guide • Technical References • System Maintenance Files • System Test Models • Conversion Procedures • OperationsOperators Manual • On-line help • Wall Charts • Keyboard Layouts or Templates • Newsletters Good documents cannot improve messy systems. However, they can help in other ways. The following table shows how documentation support the software development process. Software Engineering 32 J.E.D.I If the user manuals are developed during.... Then, the manuals can... Product definition • Clarify procedures and policies • Identify unfriendly elements • Increase changes of user satisfaction Design and Coding • Clarify bugs and errors • Identify causes of unreliability • Force designer to make early decisions Distribution and Use • Help users adapt to the product • Warn against bugs in the system • Disclaim liability Table 2 Documentation Significance There are two main purpose of documentation. Specifically, they: • provide a reasonably permanent statement of a systems structure or behavior through reference manuals, user guides and systems architecture documents. • serve as transitory documents that are part of the infrastructure involved in running real projects such as scenarios, internal design documentation, meeting reports, bugs etc.

1.7.2 Criteria for Measuring Usability of Documents

A useful document furthers the understanding of the systems desired and actual behavior and structure. It serves to communicate the systems architectural versions. It provides a description of details that cannot be directly inferred from the software itself or from executable work products. Some criteria for measuring usability of documents are listed below: 1. Availability. Users should know that the documents exists. It must be present when and where needed. 2. Suitability. It should be aligned to users tasks and interests. It should be accurate and complete. Related documents must be located in one manual or book. 3. Accessibility. It should fit in an ordinary 8.5in x 11in paper for ease of handling, storage, and retrieval. It should be easy to find the information that users want. Each item of documentation should have a unique name for referencing and cross-referencing, a purpose or objective, and target audience who will be using the document. Referrals to other manuals and books should be avoided. 4. Readability. It should be understandable without further explanation. It should not have any abbreviations. If you must use one, provide a legend. It should be written in a fluent and easy-to-read style and format. Software Engineering 33 J.E.D.I

1.7.3 Important of Documents and Manuals