Articles

Producing Technical Documentation Part 1

By Colin P Dunbar

There is nothing mystical or special about effectively producing documentation. All it takes is logic.

Producing quality documentation, cost-effectively is not a matter of putting writers and illustrators together with paper and pens (or PCs), and then hoping to get effective manuals from the endeavours. Rather it is a disciplined and controlled exercise, almost like a military maneuver. Well thought out planning and control measures are required, and if not implemented from the start, it can and usually does result in definite things occurring:

1. poor quality documentation,
2. unrealistic documentation costs.

What effective production is

Effective production is the TIMEOUS completion of ACCURATE, COMPLETE and USABLE documentation. Where any one of these criteria are not met, the entire documentation process, from initial production to end usage can fail dismally.

Before anything, it must be realised that TIME is directly related to COST:

1. If the documentation is not completed on time, the deadline must be extended, and this usually results in overtime rates for the documentation staff (not budgeted for). Delivery of the product can be delayed as result, resulting in penalties, and poor customer relations. Neither of which is good for business.
2. Where the documentation is inaccurate or incomplete, the result is that parts, or the whole, of the documentation need to be reworked. And inaccurate documentation can result in injury or even death to personnel, or damage to the product. Again unnecessary costs, and certainly poor relations with the customer.
3. The results of unusable documentation are identical to the factors mentioned in (2) above. An added drawback of poor quality is that the documentation will not be used, and as a result the product will not be utilised or maintained as required.

The first step: preparation

On larger projects, before planning is commenced with there are certain preparation aspects which need to be dealt with. Spending the time in conducting effective preparation will be well worth it when the project gets under way.

Although preparation differs from project to project, and also depends on the size of the project, there are basic rules applicable to preparation. Preparation should include, amongst others, the following criteria:

1. Familiarisation and clear understanding of the specification or standard, and where applicable, the scope of work or outline.
2. Comprehensive details of what information will be required and from who (this is usually a good time to compile a Request for Information (RFI) form). This should be done in conjunction with the specification and the scope of work.
3. Compilation of an internal standards document (separate from the specification); this would contain elements like standard terms, accepted spellings, abbreviations, etc. This often is an on-going process, depending on the size of the project.
4. Development of control, QA, review, etc. procedures.

In essence the preparation stage of a project should attempt to cover the "unforeseen" aspects of documentation production. And in large projects, these can be numerous.

Next: What affects documentation production.

---

Please don't hesitate to contact us, for further information, or give your comments. E-mail: info@cyberdoc.co.za Tel: (011) 421-1434. Your enquiry will be dealt with in less than 48 hours.