Last update PvD
<Component> - <Aspect>
|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:
|Documentation is like sex: when it’s good, it’s very, very good; when it’s bad, it’s better than nothing.|
|This section is concerned with the document itself (and not with the document's subject). It provides context for the document.|
Application NoteIndicate what this document is about and what it is to achieve (and what not). Specify what the intended reader audience is, and the required (level of) knowledge.
The subsection Scope can –in particular for less technical documents– be replaced by a Summary: a short description of the contents of the document, and in particular of specific results/conclusions.
(In this example 'Contents' is a normal header, but that is not always practical.)
|0.3 Reference Documents|
|0.4 Edition History|
|0.5 Abbreviations & Terms|
|1.1 Header Level 2|
|1.1.1 Header level 3|
|2. Documentation Standard|
|2.2. Document Identification|
|2.4. Draft & Approved Editions|
|3. Documentation Plan|
|3.2.1 Handling Critisism|
|3.2.2 Mark Changes|
|3.3 Change Procedure|
|3.4 Document Examples|
Specify all documents which are relevant.
Highlight documents which are a pre-requisite to use/understand this document (i.e. 'essential references').
|Specify the last couple of editions, and the highlights of the changes|
|v1||yyyy-mm-dd||<First release (of v0.f). Adaptation for …>|
|v2||yyyy-mm-dd||<Added chapter on … to reflect Change Note 7, minor corrections, …>|
List abbreviations and special terms used in this document.
For a project you will probably have a separate document with all common abbreviations and terms. You should refer to that document in the Reference Documents-section.
However, some documents will use aspect-specific terminology which is not generally relevant; to avoid polluting the common Abbreviations & Terms-list with rare terms, this is the section to use for specific abbreviations & terms in this document (probably next to a reference to the common list).
|CRB||Change Review Board|
the committee that will decide on Change Requests which have (major) impact
Version of a document
|Variant||Variant version of a product (component) and corresponding documents|
|WWW||World Wide Web|
the internet for browsers
Header level 1 (chapter) commonly starts a new page.
Introduce the reader in the subject, provide context.
Provide a kind of summary of the document's subject, and a document structure.
|Example of header at level 2 (major section); uses a chapter sub-number.|
|Example of header at level 3 (minor section). Usually 3 levels is sufficient.|
|Example of bulleted list: (a two-level list can be usefull, more is unlikely)|
|Example of numbered list (potentially also alphabetic, i.e. with letters):|
|Example of references:|
Reference to other sections in this document:
Example: see previous example in section 1.1.1.
Reference to figures & tables in this document:
Example: see Figure 1: <caption> (in HTML-documents you should use a hyperlink).
|Example of figure:|
Figure 1: Use a <caption>
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.
Documentation reflects what has been agreed upon. That doesn't mean it can't change, but only after approval by the appropriate responsible(s).
It implies that all documents —or changes to documents— must be reviewed before being officially issued. See section 3.2 Reviews for that.
A Documentation Standard is to make your life easier. A standard document template —like this document— helps to get desirable information in the document.
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.
|Requirements||"||DS (design specs)|
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)>|
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.
It is also clear that documents should be reviewed and approved by several capable people before it is released. See section 3.2 for more about Reviews.
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.
A Documentation (Management) Plan is a document that describes:
the documentation standard:
and the documentation effort:
For any project the Documentation Plan provides a good indication of the required (documentation) effort.
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).
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).
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.
Most word processors have a facility to mark changes in a document (typically and
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.
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.
However, when a change to a document is also a Change to the system or the project, it may have serious impact on the system or the (development) project, and should therefore only be decided after serious deliberation. See Change Procedure for more info on this subject.
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):