Return to Articles.

Producing Technical Documentation

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.

Who affects documentation production

As mentioned previously, it is important that the documentation production plan be made known to the other members of the production cycle. If it is not known, the technical personnel will not be aware of their role in the cycle.

If for instance, the technical writer requires source material or needs to do research with a specific engineer or developer, that person must either make the source material available, or be available to answer the writer's questions.

If, as often occurs, the technical persons do not have the time to accommodate the writer, the result will be delays in the production of the documentation. . An efficient method to work around this is to implement a system (during the preparation stage) of advising all the suppliers of source material approximately when they will be contacted, and if possible what information will be required from them.

Departments or persons that have a direct influence on effective production are, amongst others:

  • Managers
  • Engineers
  • Developers
  • Draughts persons
  • Technicians
It can occur that a department, instead of a single person, will be responsible for making source material available. Depending on the type of documentation and the size of the project, all the persons listed above will need to contribute effectively to the production cycle. If this occurs, one person should be given the responsibility of being the coordinator for the supply of the source material.

This practice though is not recommended, without careful assistance from the writer, as it is always more cost-effective and productive to have the writer conduct his own research. When non-documentation persons are required to make source material available, this usually results in delays.

Understandably, a technician feels he is employed to perform the duties for which he was trained, not to help someone else to do his job. Often persons are surprised at the time involved to do research, and what exactly is involved in producing technical documentation.

The decision makers in the majority of commercial organisations have no knowledge of the principles or procedures of technical documentation, and as a result are not interested. This is largely due to no fault of their own, but rather due to the policy of the organisation, towards documentation. It is an unfortunate fact that most commercial organisations regard documentation as a "nice to have" luxury that they can do without.

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.

What is effective technical writing?

Measuring effectiveness in technical writing may be somewhat difficult, especially to the unknowledgeable. It does not necessarily mean that the person who sits at his desk from eight to four, is effective. The effectiveness must be judged on various elements, amongst which are:
  • Clear writing
  • Appropriate graphics
  • Applicable charts
  • Suitable binding method
Where the technical writer gets to a point where he has to wait for source material is an area where a writer can be either an asset or a liability to the effective production of the documentation. The effective writer will not sit at his desk doodling, but continue with another part of the document, or if not at all possible, he can review material that he has already written.

The situation mentioned in the previous paragraph can occur often, but can also be avoided with effective planning. The overall planning of the documentation project should accommodate such "quiet times" and attempt to keep production flowing.

The writing function

After planning, the next step in effective production is the actual writing function. And here, depending on the size of the project it is the role of the writer that has the greatest influence on the effectiveness of the production.

Effectiveness of the writer is directly related to time, and consequently to cost. As a result the writer should be ever-conscious of the disciplines which follow in the production cycle. The foundation of a documentation project is the writer's draft, and has an effect on the review, editing and illustrating functions. A well organised and written draft will avoid unnecessary time taken by the review authority and editor. In this regard it is important that the writer work closely to the specification.

The illustrating function

The consideration of the writer for the illustrators is important in having clearly identified the illustrations. It is not a matter of the writer wearing two hats; that of writer and illustrator. But he should have a clear understanding of technical illustrations. Clearly identified illustrations or sketches will enable the illustrators to be more cost-effective, and avoid unnecessary liaison with the writer, which can be a waste or productive time.

Technical illustration has possibly more artistic elements than technical writing. This is especially true for airbrush work, cut-away orthographic illustrations, and some perspective illustrations. These require an artistic talent, although they are depicting technical items.

Although the aforementioned illustrations have a purpose in documentation, a large volume of the graphic/illustration work in documentation today comprises screen captures from software programs.

Measuring productivity

In almost every sphere of industry and commerce, productivity is a prime concern of management. Technical documentation is no different. Albeit, determining productivity in documentation is not quite the same as in a manufacturing environment. It is not necessarily the number of pages written or the number of illustrations generated.

Measuring productivity, or determining methods of increasing productivity in the documentation industry is not a simple task. This is largely due to the fact that the disciplines in documentation are a combination of "science" and "art". The technical aspect forming the "science" part, and the writing and illustrating naturally forming the "art" part.

Return to Articles.

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.

This article was printed from the web site of CYBERDOC cc (www.cyberdoc.co.za).