Internet/Intranet
The Internet has become a rich source of information, including computing
systems documentation. Information about all types of hardware and
software can be found. Some information comes from the suppliers,
although much of it is from other parties.
Documentation is often found on an organisation’s intranet. For example,
the Intel website (www.intel.com) provides technical specifications of hardware
components.
Help files
Help files are common in many applications, reflecting the increasing
popularity of online documentation. Help files often provide detailed and
structured information so that the user can find what they want without the
inconvenience of a bulky manual.
Help files can now be produced in HTML format using Microsoft’s HTML
Help. These help files can be viewed by Internet browsers such as Internet
Explorer and Netscape.
Multimedia
Text, graphics, video, animation, sound and interactivity can be integrated
into online documentation – this is known as multimedia documentation
because it uses a range of communication media. Information can also be
organised as a database – this allows selected information to be retrieved
quickly and accurately, making online media dynamic and powerful.
CD/DVD
Large volumes of information can be stored on CD or DVD. This is now the
cheapest and most flexible way of providing documentation.
The purpose of technical documentation is to provide information for people
who build and maintain computer systems. Computer engineers and
technicians, network engineers and administrators, systems analysts, system
designers, data analysts, programmers, technical/manual writers
(documentation specialists) and software testers need to know how a system
works, although different people are interested in different aspects of
the system. Figure 1.3 shows a computer technician referring to some documentation
while fixing a computer.
A data analyst in charge of a corporate
database might only be interested in
knowing about the data used by the
system. Clearly there should be a
description of the data used – in this
case, in a data dictionary. A programmer,
on the other hand, is more
interested in the logic of a program – if
a program is malfunctioning. In this
case the information will be found in a
program specification, which may be
textual, diagrammatic or both. A user
manual such as a training document
requires information such as screen
and report layouts, which are provided
in the technical documentation. For
example, a writer may want to develop a sales brochure, and so refers to the
technical documentation for information about the product. A software tester
may need samples of typical data to be used with the application in order to test
the software effectively. A network engineer may need technical documentation
to set up a network.
Other people who may need to refer to the documentation include project
managers, system managers and computer operations staff.
Methodologies for producing documentation
A methodology describes the approach and the steps used in a particular discipline.
For example, accountants have methodologies for preparing
financial reports, software developers have methodologies to prepare software,
and technical writers have methodologies for preparing
documentation.
A widely accepted methodology for developing computer system documentation
is the standard documentation process. The starting point in this
process is the document library blueprint – this is a description of the
different types of documentation required (such as training manual,
procedure manual, online help). It is a specification of the documentation
to be produced.
The document library blueprint is used to obtain user acceptance and project
management approval for the form, style and purpose of the
documentation. It also serves as a planning aid in development.
Individual document blueprints are specified after the document library
blueprint has been approved. These individual specifications are more than
an outline. They identify the context of the document, its purpose and the
detailed content. Figure 1.4 shows the stages and their sequence in the
standard documentation process.
The development of the documentation is a project in itself, and so good
project management methods are needed. The development of computer
system documentation has its own life cycle. As shown in figure 1.4, the
stages that make up the development process are:
planning
drafting
reviewing
testing
producing
distributing
updating.
Planning
As in other disciplines such as constructing a building or developing software,
planning is essential. Just as a builder
would not start building a house without a
schedule, specification and budget, you should
not start writing the documentation without planning first. As part of the
planning process, you need to:
create a document library blueprint
determine the resources required
develop a schedule
determine the budget.
Creating a document library blueprint
Creating the document library blueprint involves identifying all the pieces of
documentation and how they are related, and developing a specification for
each – known as the document specification. The document library blueprint
and specifications provide the information the authors need to produce the
documentation.
The individual document specification covers the document’s:
purpose
audience
— characteristics
— needs
— diversity
related documents
media
production plan
reviewing and testing
update plan.
These should be specified to a level of detail that will enable a documentation
developer to produce the documentation. They should be sufficiently
clear and detailed for another person to use them.
Purpose
The purpose of the document is to define the reason why this documentation
is produced. This may be addressed in the form of objectives for the documentation.
The following are some examples of technical documentation
objectives:
to enable a person to assemble a computer
to enable a software engineer to change software
to help a database administrator to manage a database
to assist a computer technician to repair a computer.
Intended reader
The intended reader or user must be identified. Their background and any
other relevant factors related to their use of the computer system must be
stated. Factors such as language, culture, attitudes and environment may be
important. The characteristics of the reader are often described in the final
documentation. Figure 1.5 shows a description of the reader given in the
introduction of the banking ma