Documentation process

We work closely with the client and follow a process that is designed to lead to high quality of the documentation. We are flexible to adapt to the in-house processes followed by our clients. The approach we follow and recommend is:

Prepare

  1. Get to know the requirements and needs of the client.
  2. Select appropriate people for the job.
  3. If necessary, train the people to gain enough knowledge and understanding of the specific subject area. The training may be delivered by the client as the bearer of the domain knowledge.
  4. Get to know the product for which documentation will be prepared and the people that will use the documentation:
    • Read the requirements;
    • Read any other existing documentation;
    • Play around with the product;
    • Interview development staff: analysts, developers, testers, and product managers who participate in creating the product;
    • Interview users (if applicable).
  5. Setup the working environment:
    • Install and configure the tools necessary to prepare the documentation;
    • Install or receive access to the product that will be documented;
    • Acquire contact information for the people that will be used as sources of knowledge about the product.

Plan and Outline

  1. Prepare a work plan. In the course of the work the plan is revisited and adjusted weekly or bi-weekly based on progress, changes in the product and requirements, risks, changes in staff, and so on.
  2. Prepare an outline of the documentation.
  3. Have the outline reviewed by an editor and by the client. The outline:
    • specifies the topics that will be prepared,
    • gives the structure of the documentation,
    • suggests for each topic: title, type, keywords, intended content, links to related topics.
  4. Iterate as necessary until the outline is approved.

Write and Edit

  1. Prepare the individual topics and submit them for review on an ongoing basis. Work as closely as possible with development, especially if detailed specifications or design are missing. A topic that is submitted for review is complete with (any of the following may be excluded if not relevant to the topic or nature of the documentation):
    • Title,
    • Texts,
    • Any examples – texts or images,
    • Index keywords,
    • Links to related topics,
    • A place in the table of contents.
  2. Have each topic reviewed by an editor. Depending on the nature of the documentation, topics may be reviewed by domain or technology experts as well. For example, if preparing documentation for an accounting program, the topics will be reviewed by accountants and developers.
  3. Test specific topics or entire parts of the documentation with representative users to check their ability to find, read, and understand the information.
  4. Iterate until each topic is approved.
  5. Submit the complete documentation for review and approval by the client.

The approach outlined here works equally well when preparing documentation from scratch or when updating an existing project. The steps are not followed in a strict sequence; a lot of overlap is possible. Certain steps may be skipped if not applicable.

Progress Tracking and Reporting

Writers and editors report their progress on a daily basis. The daily reports specify what has been accomplished and raise issues that need clarification.

Depending on the scope and nature of the project a daily meeting is usually appropriate where progress and issues are discussed and tasks are assigned.

A weekly progress report is prepared and delivered to the client.