Planning documentation

From TechWriter Wiki

Jump to: navigation, search



Long before writing actually starts, it is necessary to thoroughly plan the documentation. This is as important for a one-page flyer as it is for a complete suite of documentation for a large-scale system. Good planning can prevent a costly and time-consuming rework later.

When planning the writing or production of a document, consider:

  1. The target audience; (see Defining the audience)
  2. The type of document; (see Deciding on the type of document)
  3. How the document will be used; (see Determining how the document will be used)
  4. What source information is available; (see Collecting and storing information)
  5. How the document will be printed (if at all); (see Printing)
  6. How the document will be distributed (if at all); (see Distribution and dispatch)
  7. What is the best format for the document; (see Document format)ยท
  8. What standards the document must conform to; (see Styles and standards)
  9. What legal requirements must be met; (see Legal responsibilities of Technical Communicators)
  10. In what application the documentation will be developed;
  11. Who will do the work;
  12. By when the document must be available; (see Scheduling)

Although there are a multitude of considerations in theory, in practice it is more than likely that several of these factors will already have been decided (for better or worse) by the client (client here is taken to mean the person or organization commissioning the document). One could initially be forgiven for thinking that a reduction in the number of decisions that need to be made is a good thing. However, the converse is usually the case, as decisions made in one area limit the possibilities in other areas.

Producing a Terms of Reference

For any documentation project it is essential that the Terms of Reference be defined before work even starts. The Terms of Reference should identify the scope and purpose of the document (see "The scope and purpose of a communication"), and should clearly specify the responsibilities of all people involved in the production of the document.

Although the responsibilities of the Technical Communicator are almost always clear, the Technical Communicator will need to work with other personnel for some aspects of the work. Identifying these people and what is expected of them early on will pre-warn them and allow them to plan their work better. It will also provide a good basis for clarification should disagreements arise further down the line. (Of course it is essential that these people receive, and agree to be bound by, the Terms and Conditions!)

In particular, the Terms and Conditions should identify who is responsible for performing the following activities, on which the writer will be dependent:

  • Providing source information (such as details of the product or system being documented);
  • Producing any illustrations required (see also "Commissioning illustrations");
  • Performing quality assurance of the document (including proofing, technical accuracy checks, etc.);
  • Granting final approval (sign-off) of the document before printing or release;
  • Printing the final document (or producing camera-ready copy for commercial printing).

Note that the Technical Communicator himself (or herself) may be responsible for one or more of these activities. For example, the Technical Communicator may be responsible for performing all quality assurance. The Technical Communicator may be responsible for printing the finished document, or only for producing text that will be incorporated into a larger publication (for example by the DTP department). All of these issues must be resolved and documented in the Terms of Reference.

Producing a Synopsis

Synopsis: A brief or condensed statement presenting a combined or general view of something; a table, or set of paragraphs or headings, so arranged as to exhibit all the parts or divisions of a subject or work at one view. [OED]

A synopsis is effectively a high-level summary of the (proposed) contents of a document (or documentation set). A synopsis is useful for clarifying the scope of the document (see "The Scope and Purpose of a Communication" on page 1), and allows the client and the Technical Communicator to confirm that they have the same understanding of what is to be produced. This can avoid nasty `surprises' when the first draft is delivered.

A basic synopsis can be developed by taking the proposed table of contents of the publication and writing a brief paragraph under each heading, describing the contents of each chapter or section. For example, a synopsis for this document could include the following entry:

Defining the Audience
This section will provide an explanation of the seven basic characteristics that should be identified for the planned audience, and describe how the values of these characteristics directly influence the publication. The section will also suggest possible ways of gathering this information.
Estimated length: 15 pages / xxxx words.

As shown in the above example, it is also advisable to provide an indication of the level of detail that the document will go into, and (related to this) the anticipated size of the document. Where practicable this should be done at the section or chapter level. Alternatively it can be done for the entire document. Sizing estimates may subsequently be used for bidding or costing purposes, so it is important to make the estimates as accurate as possible.

If a separate Terms of Reference is not being produced, then it is worth including details of the type of document to be produced, and the target audience of the document. It may also be beneficial to specify the development tools and the distribution format, if this is not specified elsewhere.

A synopsis is worth producing on long projects, even if just for the benefit of the Technical Communicator writing the document(s), and can form a valuable yardstick throughout the course of the project:

  • At the start of the project, it will ensure that the Technical Communicator has fully grasped the size of the project and the amount of work required. This will help with planning and scheduling the work.
  • During the course of the project, it will provide the Technical Communicator with an overview of exactly what has been documented already, and what remains to be documented. This will ensure that the Technical Communicator doesn't get ahead of himself (or herself)and document functionality (or other information as appropriate) in the wrong section.
  • Finally, at the (perceived!) end of the project, it will allow the technical Communicator to check that they have not forgotten anything that was in the original scope of the document.
Personal tools