Definition of system documentation
Documentation may be intended for various target audiences, such as management, technical staff, planners of other quarters, and users. It should be readily accessible, up to date, timely as to ensure relevance, and comprehensible to its main audience. It can be multimedia format (e.g. hard copy, electronic format and visual presentation). Care must be taken to preserve the integrity of the documents.
Purpose of System Documentation
- They should act as a communication medium between members of the development team.
- They should be an information repository to be used by maintenance engineers.
- They should provide information for management to help them plan, budget and schedule the software development process.
- Some of the documents should tell users how to use and administer the system.
- They may be essential evidence to be presented to a regulator for system certification.
Documentation produced during a software project normally falls into two classes:
- Process documentation
These documents record the process of development and maintenance. Plans, schedules, process quality documents and organizational and project standards are process documentation.
- Product documentation
This documentation describes the product that is being developed. System documentation describes the product from the point of view of the engineers developing and maintaining the system; user documentation provides a product description that is oriented towards system users.
Guidelines for creating a system documentation.
- The level of documentation should consider the target audience for which it is intended. As a result, it must be determined whether documentation should be detailed or condensed, technical or general.
- The scope of the documentation should take into consideration the context in which the the system was created, the importance of the system, whether it is new or recurrent, and whether it is similar to or different from other system. This determines what must be covered by new documentation and what can be covered by references to existing documentation.
- Documentation priorities should also take into account the system development budget, the appropriate time for publishing the documentation, as well as its short-term and long-term benefits.
- End-users use the software to assist with some task. They want to know how the software can help them. They are not interested in computer or administration details.
- System administrators are responsible for managing the software used by end-users. This may involve acting as an operator if the system is a large mainframe system, as a network manager is the system involves a network of workstations or as a technical guru who fixes end-users software problems and who liaises between users and the software supplier.
- Use active rather than passive tenses. It is better to say ‘You should see a flashing cursor at the top left of the screen’ rather than ‘A flashing cursor should appear at the top left of the screen’.
- Use grammatically correct constructs and correct spelling to boldly go on splitting infinitives (like this) and to misspell words (like mispell) irritates many readers and reduces the credibility of the writer in their eyes. Unfortunately, English spelling is not standardized and both British and American readers are sometimes irrational in their dislike of alternative spellings.
- Do not use long sentences that present several different facts It is better to use a number of shorter sentences. The reader does not need to maintain several pieces of information at one time to understand the complete sentence.
- Keep paragraphs short. As a general rule, no paragraph should be made up of more than seven sentences. Our capacity for holding immediate information is limited. In short paragraphs, all of the concepts in the paragraph can be maintained in our short-term memory, which can hold about 7 chunks of information.
- Don’t be verbose. If you can say something in a few words do so. A lengthy description is not necessarily more profound. Quality is more important then quantity.
- Be precise and define the terms which you use Computing terminology is fluid and many terms have more than one meaning. If you use terms like module or process make sure that your definition is clear.
- If a description is complex, repeat yourself. It is often a good idea to present two or more differently phrased descriptions of the same thing. If readers fail to completely understand one description, they may benefit from having the same thing said in a different way.
- Make use of headings and subheadings. These break up a chapter into parts which may be read separately. Always ensure that a consistent numbering convention is used.
- Itemize facts wherever possible. It is usually clearer to present facts in a list rather than in a sentence. Use textual highlighting (italics or underlining) for emphasis.
- Do not refer to information by reference number alone. Give the reference number and remind the reader what that reference covered. For example, rather than say ‘In section 1.3 …’ you should say ‘In section 1.3, which described management process models, …’