ABOUT
SERVICES
STORIES
ARTICLES
CONTACT

To view this article in PDF format, click click here.

Guidelines For Producing Effective Documentation

This article is intended for subject matter experts (engineers, researchers, product managers and project managers) who need to work on documentation projects with a technical or marketing writer. The following guidelines are intended to help both you and the writer assigned to the project in producing clear and easy to read documentation.
 

Rule 1 Never consider the time you invest in writing or planning documentation as wasted time

Like any well designed project, the production of good documentation requires clear planning and a considerable investment of time and resources. This may seem like a pain to you, especially when you are overloaded with other work. Rather than viewing documentation and the lengthy meetings with the "non-specialized" technical writer who needs to be explained step by step the simplest things, as a necessary evil, you should see it as a tool for helping you clarify your product to yourself as well as to others.

One of the problems of design is that when you get bogged down in the gritty details and mechanics you may lose site of the forest, for all the trees. Documentation not only provides you with a roadmap of the forest, it also presents an overall perspective, an opportunity to step out of the loggers "mindset" and see the larger plan or goal. Where are you heading? Are you missing anything? Have you included everything that needs to be included on the way?

Through discussions with writers you may identify problems which you were not aware of before. At the very least, the documentation process helps you to place what you are doing in perspective and keep in focus the ultimate purpose of the product being designed and the user.

Preferably an outline should be produced that covers the major sections of the documentation and that is designed to lead the reader in a logical manner through the task, procedure or description being described.

Make sure your time allotment for a project takes into consideration time devoted to documentation.

Rule 2. Don’t take what you say or write for granted

What may seem clear and obvious to you, may not appear so to someone from outside the company, who is not familiar with the concepts and jargon that you use daily.

When a writer or user asks you just what you mean by something, the answer may seem "obvious", but it may not be. Language needs to be taken apart, examined for its basic concepts and then reassembled again. Often, drafts need to be rewritten several times, to clarify the meaning and focus the text to fit the reader's needs.

Information that is presented from a "technical" perspective needs to be presented in a form suitable for the purpose of the document and the intended reader. Readers of manuals or brochures will probably not need to know any technical details, other than on a broad, conceptual level. This requires removing information not relevant to the reader.

Rule 3. Provide lots of feedback and input

The basic formula for documentation is:

Quality of input = quality and clarity of output

Remember this formula the next time you give feedback. Writers are dependant on receiving good quality information. You are responsible for ensuring that the information you provide is comprehensive and accurate.

Feedback should be concise and to the point. It should:

  1. Refer to specific items in the document.
  2. Provide clear guidelines for what needs to be changed.
  3. Preferably be presented as a list of to do items or as text to be edited/changed in the document.
Sometimes, you may not be sure of the exact problem with the documentation. Something may feel wrong or missing in the documentation, a description of a concept or procedure may feel incomplete. Trust your gut feeling and explore this further. You know the product. Ask yourself or the writer "What do you mean by this?" Try rephrase unclear sections in a way that communicates the way you see the product.

Use diagrams and examples to explain what you mean.

Finally, if a writer requests information or feedback, don’t procrastinate and delay. This holds up the entire documentation process, since the writer cannot proceed until your feedback or information has been received.

Rule 4. Be prepared for lots of drafts

Clear documentation, like any other activity, requires constant rethinking and reshaping. Concepts, terminology and processes need to be identified, written about, clarified, rewritten about, discussed and honed. Writing is a cyclical process. Each round of feedback produces a document that is clearer to read, more comprehensive and accurate. The more input from different perspectives and different readers, the more reliable and accurate will be the nature of the information you produce.

Unfortunately, the myth of dashing off a draft in one sitting that contains everything that needs to be said in a clear way, is impractical. It would be similar to asking a software engineer to produce a program in one draft.

Rule 5. Be on friendly terms with your writer

The writer assigned to your project is there to help you. He/she is not an added nuisance that is a drain on your resources and time. Their purpose is to take all the problems and considerations that go with documentation off your hands.

The task of documenting a project is both lengthy and time consuming - that is why technical writers are employed to take this responsibility away from you. This allows you to devote your energies where it’s most needed - to the product design.

Don't cut short or avoid your writer, for fear of wasting your time. Your patience will pay off.

Rule 6. Make sure all stages of design are well documented

It pays to invest time and energy in the beginning in clarifying the concepts of your design, through white papers, business plans, presentations, diagrams and SRSs  (Software Requirements Specifications). The more thorough the documentation, the more information will be available at a later stage for user-orientated manuals and other external documents.

Rule 7. Involve your writer in all stages of the product design

Your writer is a valuable resource. Don’t involve him/her at the last stage, in the final rush to complete the project.

An experienced writer will be able to provide a bird's eye view of the entire project and its components. Such a writer can integrate and synthesize information from different sources, written over different time periods. A writer who has been involved in all stages of documentation will be able to fill in gaps and make critical decisions about the contents of a manual, with the minimum of investment from the product manager and engineers.

Rule 8. Writing is team work

The final documentation product should be the result of the combined input and feedback from the entire team - engineers, product managers, writers and QA (quality assurance) reviewers. Each person can add something from their own perspective that can contribute to the value of the document. Remember this when you are asked to offer feedback and input or if it is your task to coordinate and ensure that other members of the team contribute their feedback.

Rule 9. Be flexible in your expectations and demands

Be prepared to be flexible in your expectations and demands. You may have to share a writer with several other product managers, each with their own deadlines. A busy writer, with several projects on hand, may not be in a position to drop everything else and devote all their time to your project. It’s important, therefore, that you plan your documentation needs, together with the writer, in advance. This will enable him/her to schedule time for you in advance.

Review Checklist

An example of a review checklist, which can be used when evaluating a document and providing review, is included on this site. To download the checklist, click here.