Documentation
20/12/12 09:24 Filed in: Management
Most “engineers” are not fond of writing documentation … after all they like building things not writing about them … they will generally agree that documentation is important and that they like to receive good documentation for things that they use. So in spite of some reluctance to do it we all agree that we want good documentation. So why is there so much bad documentation out there?
One of the problems with writing good documentation is there are many dimensions to documentation. Some of the more neglected and confused that tend to lead to poor documentation are:
Good documentation is written for someone else! Even if you anticipate only using a document for yourself you are writing for yourself in the future at a point in time when you have forgotten what you knew when you wrote the documentation in the first place (otherwise you would not be looking at the documentation in the first place).
The short cuts you make when you write documentation for yourself generally harm its use for others, handing your personal idiosyncratic documentation over to a group without considering the audience is unlikely to result in a document that is regarded as good and useful.
Good documentation is generally written for a person of a general standard with a general appropriate level of knowledge in your target audience. The audience may be small - such as engineers in your company; but it should include the least knowledgable member of the team.
Some documents have a short life time - what they refer to will cease to exist (e.g. decommissioning equipment) or the circumstances to which they are relevant will pass (eg. Y2K documentation) - however, most documents tend to have a less knowable lifespan when they are written. The worst problems arise in documents that are written for the short term, but are in use long after the period the document was written to cover.
Better documentation addresses the time issue by being written with an eye to the future … anticipate that the document will be in use longer than the obvious time (of course documents for strictly limited circumstances may not need this) and documents should be maintained to ensure that the information is up-to-date and remains useful.
Documents that are out-of-date and worse with misleading information - even if it is in a separate section - are viewed suspiciously and less trusted.
If you can’t find the document, the right version of the document or retrieve the document from where it is needed then it is hard to regard the document as good. Many organisations use e-mail, Word and Excel to create and disseminate documents but do not create a management structure to ensure that the correct versions of the documents can be found and identified quickly.
Revoking old and out of date documents is almost as important consideration as getting new documents in to the hands of the user.
Some strategies for managing distribution and retrieval:
- target audience
- temporal relevance
- distribution and retrieval
Target audience
Good documentation is written for someone else! Even if you anticipate only using a document for yourself you are writing for yourself in the future at a point in time when you have forgotten what you knew when you wrote the documentation in the first place (otherwise you would not be looking at the documentation in the first place).
The short cuts you make when you write documentation for yourself generally harm its use for others, handing your personal idiosyncratic documentation over to a group without considering the audience is unlikely to result in a document that is regarded as good and useful.
Good documentation is generally written for a person of a general standard with a general appropriate level of knowledge in your target audience. The audience may be small - such as engineers in your company; but it should include the least knowledgable member of the team.
Temporal relevance
Some documents have a short life time - what they refer to will cease to exist (e.g. decommissioning equipment) or the circumstances to which they are relevant will pass (eg. Y2K documentation) - however, most documents tend to have a less knowable lifespan when they are written. The worst problems arise in documents that are written for the short term, but are in use long after the period the document was written to cover.
Better documentation addresses the time issue by being written with an eye to the future … anticipate that the document will be in use longer than the obvious time (of course documents for strictly limited circumstances may not need this) and documents should be maintained to ensure that the information is up-to-date and remains useful.
Documents that are out-of-date and worse with misleading information - even if it is in a separate section - are viewed suspiciously and less trusted.
Distribution and retrieval
If you can’t find the document, the right version of the document or retrieve the document from where it is needed then it is hard to regard the document as good. Many organisations use e-mail, Word and Excel to create and disseminate documents but do not create a management structure to ensure that the correct versions of the documents can be found and identified quickly.
Revoking old and out of date documents is almost as important consideration as getting new documents in to the hands of the user.
Some strategies for managing distribution and retrieval:
- Wiki - with access control, central management and ubiquitous access; this solution works well for many organisations
- Document management software - managing versions and access control gives confidence that the right document is being accessed and from a single location
- Central document store - at least the documents are all in one place and with a bit of careful naming versions can be identified
- E-mail the documents out - if the documents are carefully named and all the users are notified this can work; but it requires a lot of care, attention and is prone to error.