<Project/Product>
<Component> - <Aspect>
 

Application Note

This document discusses important issues for (technical) documentation.  It is also a template for such a document. Replace all text between <angle brackets>, adapt and complete other texts. Remove all the Application Notes like this one (boxes with yellow background). On the Document Title: Project / Product: self explanatory (e.g. Gromo-project, DSLAM, Company Rules); Component: self explanatory, part of the Project/product (e.g. Site engineering, Management board, Software engineering); Aspect: type of information (e.g. Assembly plan, Commands & responses, Review policies).

0.  Prologue

0.1 Scope

0.2 Contents

(In this example 'Contents' is a normal header, but that is not always practical.)

0.4 Edition History

0.5 Abbreviations & Terms

1.  Introduction

1.1 Header Level 2

• <Bulleted list>
• <next item>

1. <Numbered list>
2. <next item>

2.  Documentation Standard

2.1 Documentation

Documentation is considered overhead by many people (not in the least by programmers).  So why make documentation ?  Well, maybe except for small –trivial– constructions, documentation is describing how it is going to look like (how it is to be build), what it can do and how it can be used.  And how you can repair it when something breaks, or how to modify it when that is required.  It is like construction work:  you may build a cabin without making blueprints first, but you will never satisfactory build a house or an office building without blueprints.

If your system is not small and simple, you need documentation.  And documentation is not necessarily a text document;  drawings, schematics, etc. are also documentation, and must comply with the same rules (edition codes, reviews, …).
People working on a product are not hobbyists but professionals.  Making documentation may not be their preferred activity, but it part of their job.  They should take pride in making good documents.

Maybe except very small cases, all products (systems, projects) need some kind of formal identification for all items involved.  It is vital to have a unique name and/or number for each item.

Now most products are composed of components, and commonly a document describes some aspect (e.g. requirements, top level design, test specification, user manual) of such a component.  A simple and sufficient method for document identification is to re-use the component's identication (number), extended with a suffix to indicate the particular aspect tackled in the document.

There are various aspects to all components, but similar types of components have the same aspects.  So it makes sense to use a standardised suffix per aspect.  For that reason, the suffix is also called Document Type Indicator.

So we end up with an identification system (name and/or number) which identifies 'components', and a 'document type' extension to indicate a specific aspect described in the corresponding document.

Example:

Table 1:  Example of Document Identifications

Item	Identification	Suffix (example)
Product XYZ	1234	-
Requirements	"	DS (design specs)
User Manual	"	UM
Parts list	"	PL
Component 1	1235	-
Requirements	"	DS
Test Specification	"	TS
Component 2	1236	-
…	…	…

The document identification (including edition- and variant-codes; see below) should be included in the document, at least on the title page and in the (header or) footer of each page.  E.g.:

Id:

<document identification>

Ed:

<edition code>

Date:

<yyyy-mm-dd>

Author:

<author (initials)>

Notes:

• that some documents do not reflect a component (for example project documentation);  in such cases extra numbers must be allocated.
• you may want to add a review date and at least a reviewer to the footer.

The date refers to the date of issue.  It is not strictly required in the footer (can be somewhere else in the document), but helpful to indicate how recent the document is (in addition to the Edition Code).

Though strictly speaking, the Author is not part of the document identification, it proves to be very useful to include his name in internal documents (though not necessarily in the footer).  It allows you to contact him directly when you have questions or remarks.
For external documents (e.g. Customer Documentation, which has not the emphasis here), you would prefer a responsible department instead of the author.
Similarly, it should be clear that the document has been reviewed (for release).

During the development of a product(/system) multiple editions of a document will be made for various reasons.  First of all there may be multiple editions of the product it is describing, but also because errors must be corrected, requirements or conditions change, because insight in the problem or solution improves, more details become known, etc.

Of course one can use a new number for each new edition, but that is not a practical solution:  the component you are describing is basically the same, and you may run out of product numbers very quickly.  If a new edition of a document is issued other documents may remain the same.  So an edition code is essential to identify a particular document, and therefore it should be part of the document identification (wherever that appears).

Initially, not everything a particular document should describe is already known, fixed and defined.  Also, documents should be written in clear and unambiguous language.  Which makes it virtually impossible to write good documentation in one go.
So you may have several attempts (proposals, drafts) before a document is approved.  The status of the document should be made clear in the edition code:  have clear indicators for draft/­proposal editions and officially approved editions.
For example numeric for official editions, and letter extensions for draft editions.  So 2a indicates a first proposal after official edition 2, 2b a second proposal, and 3 the third officially approved edition.
Or use decimal numbers, e.g. 0.1 for the initial draft, 1.0 for the offical/­approved release, and 2.1 for the first proposal after approved edition 2.

Some products may have variants, like a military and a commercial version, or for vertical mount or horizontal mount, or for various languages.  Most documentation will apply to all variants, but some may be distinct per variant.  If you have hardly any variants in your products, you may decide to omit the variant code and use a separate product identification (number) for each product variant when it occurs.
A variant code is not the same as a language code (translated version of a document), but can be used for that purpose.

If your product uses variants, a variant code (commonly letters) should be added to the document identification.

If the product is improved (i.e. get a new edition) or a related document is re-issued, other documents may remain the same.  Than again, some other documents may have to be adapted as well to reflect the change.  Now the synchronisation between component and documents becomes confusing as the documents may have entirely different edition codes.  So you need a co-ordination sheet, indicating what versions of the component matches to what version the component and each of the documents, taking variants into account.

To facilitate easy referencing, it is strongly advised to use 'legal style' numbers with section headers (as used in this example).  So a reference can be short and unambiguous (e.g. see section 5.3.1).  It also allows easy searching when leafing through the document.

3.  Documentation Plan

A Documentation (Management) Plan is a document that describes:

  the documentation standard:

1. the rules which apply to all documents (regarding identification, formatting, …, or a reference to an applicable documentation standard);
2. the rules for reviews (or reference to the relevant standard);

  and the documentation effort:

3. specifies all Document Types required for each type of component;  and
4. preferably identifies all documents to be produced for the project (derived from [3] and the project's Work Break-down).

For any project the Documentation Plan provides a good indication of the required (documentation) effort.

3.1. Language

Documentation is not literature !  Using different terms for the same concept is very bad;  it may suggest to the reader that you mean something different.  For example (specifically in Requirements Specifications), do not use the words shall, will, should, would or must as alternatives, but select one of those words and only use that word.

The most important aspect of documentation (language) is to express everything unambigiously, and abstract (e.g. not prescribe solutions when that solution is not required, but describe the desired result).

3.2. Reviews

Each document should be reviewed before it is officially released/­issued (i.e. gets a non-draft Edition code).
When the author of a document thinks the document is ready for review, he will inform the documentation departement of such.  The documentation departement will appoint a review leader (usually out of their midst).

While the review is about the subject of the document, poorly written documents (or poorly drafted drawings) and abuses to the documentation rules will distract the reviewers from the subject contents.  Therefore it is wise to have a pre-review by somebody knowledgeable about the documentation rules and use of language (commonly the review leader when he/she is of the documentation departement).
When his remarks have been processed, the document is really ready for review:  the review leader selects a group of people as reviewers, sets a review date and distributes the proposed document.  The reviewers should be people knowledgeable about the document's subject;  preferably there are also 'users' of the document among them (i.e. people who will use the document in the next phase of the project).

The reviewers should study and check the document on their own in advance.  The critical aspects for the review are clarity, unambigouity, completeness and preferably abstractness (not prescribing a particular solution but the desired result).  On the review date, the reviewers gather in a meeting and discuss the document section by section.  The author and the review leader will take notes (to adapt the document).
At the end of the meeting, the review leader should ask the opinion of the reviewers whether the document is ready to be issued provided that the remarks are processed.  If not, a date for the new proposal of the document, and a date for a new review date should be set.

When the document is deemed ready for release, the author should process all remarks and submit the document to the review leader.  He/she will check whether the remarks have been processed satisfactory and release the document.
That implies some administrative actions to reflect the newly issued document (like adapting edition codes in the list of documents).
 

3.2.1. Handling Critisism

Critical remarks on a document should not be confused with critical remarks against the author.  An author has to accept that any discussion on his text shows a problem (with ambiguity, clarity, …).  As said before, it is extremely hard to write clear and unambiguous documents in one go;  it requires a critical review by others.  A joint effort provides much better results.
 

3.2.2. Mark Changes

Most word processors have a facility to mark changes in a document (typically inserted text and deleted text).  That facility is extremely valuable when checking new versions of documents;  instead of studying the whole document –often of considerable size– for changes, the changes are now clearly marked.  Only the marked paragraphs have to be really reviewed (the other sections have been reviewed before).  Change markings save a lot of time, so in most organisations reviewers will refuse documents without them.

3.3. Change Procedure

Adapting a document is obviously a change to that document, but not necessarily a change to the related project/­system component;  usually the change to the document involves providing additional information or is a quality improvement.

3.4. Document Examples

To make it easier to start documentation, the list below refers to examples of various document types (i.e. the examples may serve as a template):