Development of Documentation

Paper based technical documentation has existed in the form of books for approximately 800 years, (Bradford 1988). A number of techniques for document control were developed by the early scribes who created these books. It was not until the development of the printing press that a standard format for documentation was developed from these techniques. The format, which is still in use today, includes the following structuring techniques, (Debs 1988):

• Alphabetisation; • Annotation; • Cross-referencing; • Indices; • Section titles; • Title pages.

The technology of paper based information publishing has not developed significantly since then, (the next major development in documentation was electronic publishing media, to be discussed in section 2.17).

Before the advent of electronic publishing media, attention was focused on ensuring that the intended audience type and content of books and other paper based media better met the requirements of the reader, (Charney et al 1988). It would appear that there are two potential audiences for technical documents, (Debs 1988):

1. Informational, (the author is writing the document to provide data to the reader); 2. Educational, (the author is writing the document to teach the reader).

Authors should carefully select the target audience before actually writing a document as they need to know what the audience type will be and also to ensure that the content is set at the correct level, (Charney et al 1988). This should be done so that the document can be oriented towards the tasks the users will be expected to achieve and will be understood by those users, (Ramey 1988). One way to help do this is to involve the potential users in the design of the documents, (Knowles 1995).

These documents are usually created using a standard document creation methodology. This methodology has been defined with nine stages as follows, (Brockmann 1990): 1. Develop the document specifications;

2. Prototype the document; 3. Review the document; 4. Write the document; 5. Field test the document; 6. Edit the document; 7. Publish the document;

8. Review the published document; 9. Maintain the document.

Following on from this methodology it can be seen that Brockmann is advocating that the users of a document should be involved in the first three initial design stages, before being invited to field test a document. One other benefit of having users help design documents is that users expect documents to look familiar and will help to ensure this. Defining a departmental or corporate documentation structure is important, as people may react badly when they encounter something unknown, (Debs 1988).

There are two conflicting theories about the content of documents which will be looked at in more detail, (Charney et al 1988):

1. The minimalist approach; 2. The elaboration approach.

2.16.2.1 The Minimalist Approach to Documentation

The minimalist approach to documentation is based on the assumption that document readers want to quickly pick up the information and data they require in order to get on with ‘doing the job’, (this is called task oriented learning), (Charney et al 1988). There are a number of rules to help authors create these documents, (Carroll et al 1988):

• Focus on real tasks and activities;

• Slash verbiage, (only include text that is absolutely necessary);

• Support error recognition and error recovery, (users will make mistakes, help them learn how to correct these rather than covering everything in order to try to stop mistakes);

• Guided exploration, (this can be done by using cards with bullet points rather than textural documents).

Adult learners have particular documentation requirements, (Brockmann 1990):

• They are impatient and want to learn quickly to be able to get on with a task;

• They rarely read a full manual, they skip to the parts of direct interest;

• They learn best by trial and error, (learning from mistakes);

• They are better motivated when they start their own exploration of a subject;

The minimalist approach to documentation aims to address these issues by streamlining documents to provide only the necessary information in small pieces. This approach does have three major drawbacks, (Brockmann 1990):

1. Independent learning can result in gaps appearing in knowledge; 2. The reader needs to be self motivated;

3. It is so different to the normal documentation style that it is difficult to write.

2.16.2.2 The Elaboration Approach to Documentation

The minimalist approach targets detailed learning of tasks. The elaboration approach is aimed at readers who need a broader understanding of a subject, (Charney et al 1988).

As the name suggests, authors using the elaboration approach need to fully explain every detail of the work being described and give examples of all the topics covered. By reading this work, the reader may not gain the same task oriented skills as the minimalist documentation reader but they will gain a full understanding of what should be done.

Using these definitions it can be seen that PhD theses follow the elaboration approach, whereas industrial reports to senior management may follow a more minimalist approach. Similarly textbooks aim to give students an understanding of the subject and so are elaborate whereas process operating instructions are task oriented.

In order to provide complete documentation a document author must consider both reader types, task oriented and general learning. In order to provide for both, the author has to create two complete sets of documentation, one for each reader type.

These approaches to documentation also agree with the definition of document types given by Brockmann, (1990). Brockmann defines 4 documents:

1. Reference documents, (possibly created using the elaboration approach); 2. Tutorial documents, (possibly created using the minimalist approach);

3. Internal documents, (for example internal training material, minutes and memos); 4. External documents, (for example software user guides, warranty documents).

Using these definitions it can be seen that Internal and External documents will be made up of a combination of Reference and Tutorial documents.

To summarise the work explained in this section, there are four questions that document authors should ask themselves before publishing documents, (Kliem 1984):

1. Is the document written in a logical way?

2. Is the document functional so that the reader can use it to assist with tasks? 3. Is the document clear and easy to follow?

4. Is the document concise and to the point rather than padded out?

With these questions in mind the author can create documents suited exactly to a range of possible reader types by creating a mix of elaborate and minimalist documentation for internal and external use. The work can be published in a paper based format following the structural guidelines explained at the start of this section.

Unfortunately there are a number of problems that have been found with the paper based format. These problems will be explained next, in section 2.16.3.