Articles

Producing technical documentation - Part 3

By Colin P Dunbar

Who should conduct research

When a person, other than the technical writer, is required to obtain source material, or even worse, conduct the research, problems can easily arise. This person can obtain irrelevant information, or superfluous information, or even (and this occurs often) obtain inapplicable information. This then results in the writer needing to go back and get the correct information, sometimes this could be weeks, or even months later. And this can have a detrimental effect on the cost of the documentation; because in fact a task is being repeated.

There are numerous benefits to having a senior technical writer responsible for the coordination of the source material. But even having a senior write appointed as coordinator, he will need to to the following:

1. have been involved in the product development from very early,
2. have authority/access to all technical data relevant to the project,
3. have an in-depth knowledge of the specification, scope of work, etc.,
4. have to be the only person responsible for the coordination and the obtaining of the source material.

Although a technical writer, he may never write a document, yet his contribution to the cost-effective production of documentation will be well worth it.

From a short story to a novel, research is the basis for the success of the publication. In technical documentation, effective research is absolutely essential to the effectiveness of the documentation, and is especially important production thereof.

If one element could be highlighted that effects the cost-effective production, then that one would be research. If the documentation is to be produced cost-effectively then the research for documents must be planned and controlled closely.

What constitutes source material?

What then is source material? It is different things to different projects. In broad terms source material can comprise the following:

1. Existing documentation (if available)
2. Design specifications
3. Physical equipment
4. Software
5. System specifications
6. Engineering drawings
7. Sales/technical brochures
8. Engineer's, developer's, programmer's notes
9. Photographs
10. Test specifications

Availability of accurate and sufficient source material can improve the production process of documentation considerably. And the obtainment of sufficient source material will only be obtained with effective planning. Pete Morton, a retired technical writer, with in excess of 40 years experience, clearly defines the importance of sufficient quality source material:

"Source material if obtained in sufficient quantity and quality will provide, after verification, the content of the document, or a basis for research which will enable any gaps in the information obtained to be filled."

Having worked in both environments; being exposed to source material from the research and development stage, and only having source material available at the actual production stage, the benefits of the prior situation were obvious.

Costs were contained, the documentation was accurate, complete, usable and available at the time of the equipment being delivered. The most obvious of the latter situation was that costs were astronomical and exceeded the original estimates by several percent, in some instances several hundred percent.

Having the technical writer involved early in the project will result in him not needing to try and dig for information, at a time when most of this information is "filed" or forgotten.

When the technical writer starts late in the production cycle, the following are amongst the problems that occur:

• The original technical personnel, engineers, etc. are not available any longer, resulting in time being wasted to obtain certain source material.
• Information vital to the documentation could be misplaced or discarded, resulting in either inaccurate or incomplete data being included in the documentation.

A writer who is sufficiently skilled, and motivated, can make life easier for himself, other writers, and the other disciplines that follow in the production cycle.

Next: What is effective technical writing?

---

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.