A common system maintenance problem is ensuring that all representations
are kept in step when the system is changed. To help with this, the relationships and dependencies between documents and parts of documents
should be recorded
in a document
management system as discussed in the final part of this paper.
For smaller systems and systems that are developed
as software products,
system documentation is usually less comprehensive. This is not necessarily a good thing but schedule pressures on developers mean that documents are simply never written or, if written, are not kept up to date. These pressures
but, in my view, at the very least you should always try to
maintain a specification of the system, an architectural design document and
the program source code.
maintenance is often neglected. Documentation
may become out of step
associated software, causing problems for
system. The natural tendency is
a deadline by modifying code with the intention of modifying other documents later.
Often, pressure of work means that this modification is continually set aside until finding what is to be changed becomes very difficult
indeed. The best solution to this problem is to support document maintenance with software
tools which record document relationships, remind software engineers when changes to one document affect another and record possible inconsistencies in the documentation
Unfortunately, much computer system documentation is badly written, difficult
to understand, out-of-date or incomplete.
Although the situation
is improving, many organizations still do not pay enough attention to producing system documents
which are well-written pieces of technical prose.
Document quality is as important
as program quality.
Without information on how to use a system or how to understand
it, the utility of that system is degraded.
Achieving document quality requires management commitment to document design, standards,
and quality assurance processes. Producing good documents is neither easy nor cheap and many software engineers find it more difficult that producing good quality programs.
The document structure
is the way in which the material in the document is
organized into chapters and, within these chapters, into sections and sub- sections. Document structure has a major impact on readability
act as a basis for document quality assurance. Documents produced according to appropriate
standards have a consistent appearance, structure and quality.
I have already introduced the IEEE standard
for user documentation in the previous section and will discuss this standard in more detail shortly. However, it is not only standards
that focus on
documentation that are relevant.
Other standards that may be used in the documentation process are:
Process standards define the approach to be taken in producing documents. This generally means defining the software tools which should be used for
and defining the quality assurance procedures which
ensure that high-quality documents are produced.
Document process quality assurance standards must be flexible and must be able to cope with all types of document. In some cases, where documents are simply working papers or memos, no explicit quality checking is required.
However, where documents are formal documents,
that is, when their evolution is to be
controlled by configuration management procedures, a formal quality process should be adopted. Figure 3 illustrates
one possible process.
revising and re-drafting is an
iterative process which should be continued
until a document of acceptable quality is produced. The
acceptable quality level will depend
document type and the potential
readers of the document.
Product standards apply to all documents produced in the course of the software development. Documents should have a consistent
documents of the same class should have a consistent structure.
Document standards are project-specific but should be based on more general organizational standards.
Examples of product standards which should be developed are:
1. Document identification standards As large projects typically produce thousands
of documents, each document must be uniquely identified.
For formal documents,
this identifier may be the formal identifier
defined by the configuration manager. For informal documents, the style of the document identifier should be defined by the project manager.
2. Document structure standards
As discussed in the previous section,
there is an appropriate structure for each class of document produced during a software project. Structure standards should define this organization. They should also specify the conventions used for page
numbering, page header and footer information, and section and sub- section numbering.
3. Document presentation standards
Document presentation standards
define a ‘house style’ for documents and they contribute
significantly to document consistency. They include the definition of fonts and styles used in the document, the use of logos and company names, the use of colour to highlight
document structure, etc.
4. Document update standards
As a document is changed to reflect changes in the system, a consistent
way of indicating these changes should be used. These might include the use of different
colours of cover to indicate a new document version and the use of change bars to indicate modified or deleted paragraphs.
should apply to all project documents and to the initial
drafts of user documentation. In many cases, however, user documentation has to be presented in a form appropriate to the user rather than the project and it should be recast into that form during the production