Practical Software Engineering

Documentation and Manuals

• Documentation
• A typical list of documentation for a programming project
• Nobody reads documentation
• Forms of documentation
  • Why do users not read documentation?
  • Minimalist manual
• Manuals -- Mayrhauser section 11.3
  • Contents of a Training Manual
  • Contents of a Reference Manual
  • The Mac is Not a Typewriter
• Checklist for Documentation and Manuals

Documentation

• A formal development methodology must be used for contractors to be monitored by buyers (or project managers, etc.). Formal documents must be used for this.
• Internal (in-house) software development also needs a formal development methodology.
• Each of the boundaries between development phases should be clearly defined by issuing a document. This should state what has been accomplished during the preceding phase and present or reference all relevant documents.
• The issue of each document should be preceded by a design review which aims at evaluating and validating the draft of the document.
• The best procedure is to have the validation done as each phase is completed. The results of the validation should be reported in a written document.

A typical list of documentation for a programming project

1. Request for proposal *
2. Proposal document *
3. Any studies, papers, reports which support items 1 and 2 **
4. Preliminary specifications
5. Preliminary design document (memo plus flowchart, pseudo-code, etc.)
6. Detailed specifications
7. Detailed design document (formal report plus flowcharts, pseudo-code, etc.)
8. Documents supporting unit testing (test plans, lists of test cases and expected results, lists of errors, programmers' notebooks)
9. Documents specifying how configuration control is to be performed.
10. Documents supporting integration test (test plans, list of test cases and expected results, lists of errors, programmers' notebooks, computer records)
11. Forms describing each error by number and how it was discovered, the diagnosed cause of the error, and how it was corrected
12. Acceptance test plans and results
13. Field test plans, operational notebooks, and results
14. Documents resulting from design reviews or management decisions
15. Any related specifications and design guides.

** Copies of the contract; any quality assurance plans and documents; engineering studies of reliability, memory requirements, processing time, or prior engineering or feasibility studies, etc.

Nobody reads documentation

Most documentation is written by technicians, yet technicians frequently complain about it.

Forms of documentation

• tutorial
• task-oriented users guide
• alphabetical reference to commands
• pictorial guide to windows, icons, tool palettes
• reference cards
• specialized guides to getting started, installation etc
• hypertext style of on-line help

Why do users not read documentation?

• Impatient to start
• Skip around manuals and on-line documents
• Discouraged by large manuals

Minimalist manual

• Provides only essential information
• Only basic topics
• No repetition, summaries, reviews etc
• No welcome etc
• Modularized into small chunks directed at user's actual work
• Task oriented documentation helps people get things done

Documentation should be viewed as a creative challenge to provide information for end users.

Manuals -- Mayrhauser section 11.3

• Provide factual knowledge on all aspects of the software and its use
• use varies for user, operator etc
• Provide in depth information -- may be separate packages
• full reference manuals with cross-reference lists
• user reference guide
• systems manual
• installation manual
• operator procedures
• maintenance guide
• Provide fast access to information
• people do not read manuals cover to cover
• manuals should be well organized, accurate and consistent
• Accommodate levels of knowledge
• start with basic levels and go on to advanced
• Define all terms
• Cross-reference between phase documents
• Group related material
• Provide an index

Contents of a Training Manual

• product philosophy
• hardware/software environment
• how to start product (incl. prepare for start)
• how to use manual--progressive steps

• steps in logical order of using and learning, not alphabetically
• most basic features or usage first
• increasing sophistication
• goal of learning in each section
• whole work units
• error messages and how to deal with them examples

A.1. glossary of terms

A.2. index

A.3. short alphabetical reference section of commands (maybe as a card)

A.4. collected error messages

Contents of a Reference Manual

• product overview and philosophy
• product component/feature overview and interfaces
• state transitions between system states
• hardware/software environment, interfaces
• structure of manual

• (in alphabetic order) description of commands (features) in detail with all default parameters
• error messages
• examples

A.1. error messages, explanations, effects, system status, possible actions. Cross-reference to section that explains system component or feature.

A.2. index

A.3. short, alphabetically ordered reference card for commands.

The Mac is Not a Typewriter

• Underlining: Don't underline. Underlining is for typewriters; italic is for professional text.
• Capitals: Very rarely (almost never) use all capital letters.
• Kerning: Kerning is the process of removing small units of space between letters in order create visually consistent letter spacing. Adjust the space between letters according to your sensitive visual perception.
• Fonts: Any font with a city name has been designed for the ImageWriter. These are bit-mapped fonts. Exceptions are New York, Geneva, Monaco.
• Tabs and Indents: Many people try to use the spacebar to line up words or numbers. Use those tabs and first-line indents regularly and properly. Never use the space bar to align text.
• Widows and Orphans: When a paragraph ends and leaves the last line at the top of a page, that last line is called a widow. An orphan is a heading or first line of a paragraph left at the bottom of a page. Never leave windows and orphans.
• Hyphenations and Line breaks: Avoid too many hyphenations in a paragraph, avoid stupid hyphenations, never hyphenate a heading and break lines sensibly.
• Leading or linespace: Linespacing within a paragraph should be consistent. If even one letter or word is larger than the rest in a paragraph, the linespacing adjusts to fit the larger characters, creating uneven spacing that looks awkward.
• Justified text: Justify text only if the line is long enough to prevent awkward and inconsistent word spacing. Ragged right is more often correct.
• Hanging the punctuation: Always attach punctuation marks to the text. This prevents a . or , on a separate line.
• Serif and Sans Serif: Type can generally be classified into two major groups; serif and sans serif. Serif type is more readable and is best for text; sans serif type can be used for headlines.

Checklist for Documentation and Manuals

• Establish what documentation currently exists in the organization. Consider the job of each user in turn. Decide whether he will require a user's guide to equipment operation, a user's guide to the system or any other documentation.
• Decide which of the following methods of providing documentary support is to be used for the user documentation:
  • paper-based manual;
  • paper-based circulars;
  • expert system;
  • help facilities;
  • computer-based documentation.
• Use your own internal standards for producing the documentation. If no standards exist, decide on the format, style, presentation and method of update to be used. Get the user to assist in producing the documentation or, failing this, to vet it as it is produced.
• Get some of the potential users to try out the documentation and note their reactions and comments. Make any necessary modifications and try it out on the users again. Continue this process until the documentation is satisfactory.
• Set up procedures that will enable users to suggest changes to the documentation. Display these procedures in a prominent position, either in the documentation or on the documentation workstation.
• Establish which job title has responsibility for making amendments to the documentation.
• For paper-based documentation, establish which job title has responsibility for the physical update of the manuals.