B. Developing a Publications Department

Documentation Process

This section walks you through the process of planning and writing documentation and of getting it reviewed.

Writing a Documentation Plan

The documentation plan informs the rest of the product team about your doc plans for the product. It should be reviewed by representatives of all departments involved with the product. It should be kept up to date throughout the project, with major changes being announced when necessary.

The documentation plan is based on input from various departments. Table B-4 provides some ideas of the type of information you might get from other departments.

    Table B-4 Documentation Plan Input From Other Departments

Department Name     Relevant Information
Marketing           Product definition, product name, customer profile, 
                    feature/function product requirements
Development         Feature/function schedule, user interface concerns, 
                    error message data, names of experts on subject matter
Legal               Trademarks, product names
Customer Support    Customer profile, previous product troubleshooting logs, how 
                    to obtain technical support, names of experts on subject matter
Manufacturing and   Part numbers, product packaging, production schedules, 
Operations          shipping lead time


Table B-5 lists the components of a typical documentation plan. It is a sample only, and not all sections are relevant to all product types or publications departments.

    Table B-5 Documentation Plan Sample Topics

Topic	         Content
Product            Product name and version, brief description of the product's 
information        intended use.
Documentation      Personnel, equipment.
Revision           Differences from the documentation of previous versions of the 
information        product (if any).
Documentation      Overall objectives of the documentation set or of each book.
Documentation      Full list of documentation deliverables and the format in which 
overview           they will be delivered.
Documentation      Brief description of the chapters and appendixes in each book, with 
descriptions       the estimated page counts. (If the books in the documentation set 
                   are large, they each might require a separate documentation plan.)
Documentation      Publications schedule milestones and other milestones from the 
schedule           project schedule that affect the documentation. Publications 
                   milestones might include draft delivery dates, technical review 
                   dates, and the final document delivery date to production.
Technical review   List of technical reviewers and the projected review schedule.
Test plan          Plans for validity testing, usability testing, and, if relevant, media 
                   testing plans and dates.
Edit plan          Editing schedule and book priorities.
Localization plan  Languages into which the document will be translated, required 
                   resources, and schedule.
Documentation      Format of the documentation components, including book sizes, 
design             on-line media, and so on.
Production plan    Printing and packaging specifications.
Issues             Any projected issues that might affect documentation, such as 
                   suspected schedule slips, engineering uncertainties, or known 
                   project design difficulties.
Critical           Items needed from other groups, including the due date and the 
dependencies       impact if the information is not provided or is late. These might 
                   Prototype delivered
                   Subject matter experts designated
                   Technical product specification received
                   User interface freeze
                   Feature/function freeze
                   Alpha version of working software
                   Installation specifications
                   Beta software released to testing
                   Technical review sign-off meeting complete
                   Development freeze
                   Final list of error messages, causes, and remedies
                   Confirmed product name

Coordinating With Product Development

Documentation concerns especially affect product development at two points in the schedule: during technical review and at the end of the project.

Writing Process

This section deals with the writing of the documentation and with the handoffs the writer must deliver.

First Draft

The first draft focuses on where information goes and how it should be presented. In the writing of the first draft, the writer should focus on these tasks:

Second Draft

The second draft should be as complete as the state of the software and the specifications permit. It should be fully illustrated. The writing should be polished.

In the writing of the second draft, the writer should focus on these tasks:

Editing Process

An ideal editorial cycle includes:

There are more details in the checklists for developmental editing, copy editing, and proofreading.

As your company's publications needs become greater and your publications staff begins dealing with more projects, you will probably want to develop a company style guide covering editorial and writing guidelines specific to your publications style and your product line. Besides using Read Me First! as a model, you may want to examine some of the books mentioned in Appendix A, "Recommended Reading."

For more information on working with an editor, see Chapter 2, "Working With an Editor."

Illustration and Graphics Design

If your illustration and design needs are minimal, someone on your team such as a writer or publications manager may be able to handle graphics design and illustration coordination. However, as your needs increase, you should consider adding a production coordinator to your staff. This person can coordinate with outside vendors, contract for illustration and graphics design help, or hire permanent staff in this area when necessary.

Illustration Concerns

Processes for dealing with illustrations vary depending upon the type of illustrations, the availability of compatible screen capture software, whether you have in-house staff or are using contractors, and your budget.

If screen capture software is available for the operating system you are running, the writer is usually responsible for capturing the screen illustrations. The writer is the one most familiar with what the screen should illustrate and with the software being documented, and so can more efficiently set up the screen appropriately. However, you may want to send these illustrations on to an illustrator to be "cleaned up" for the best final reproduction quality.

Concept illustrations, on the other hand, usually benefit from having an illustrator render them. Not all writers are gifted artistically, and the time spent producing art is time not spent writing. Illustrators are also more familiar with the "language" of illustrations and can usually produce a more professional concept illustration.

The writer, illustrator, and editor should meet periodically to discuss rough sketches and specifications for illustrations.

A preliminary list of illustrations required for the project is produced by all the writers. The writers periodically review the illustrations for their specific books with the illustrator until both are satisfied with the final art.

Note - If your documentation consists in large part of updating existing documentation for a standard set of products, consider archiving generic illustrations of your product or its basic concepts for use in future documentation.

Graphics Design Process

The graphics design for your documentation set may already be established or may be standard for each book or on-line component. However, you may need a graphics design plan if you are adding new types of components to your documentation set, or if you have a new product line for which you want a different look.

Technical Review

This section explains some of the issues related to the publications team and the reviewers during a technical review process. Remember, thorough technical review is an important contribution to the accuracy and usefulness of your documentation. Unfortunately, this is sometimes a difficult concept to convey to other groups. This section provides information on how to promote and conduct a technical review.

Make sure that you provide details about the technical review, including its schedule, in your documentation plan or during planning meetings. Emphasize the importance of having accurate documentation that is thoroughly reviewed and tested. Point out the advantages this provides to the whole company in saved support costs, a good reputation, and favorable industry reviews.

Make sure that the relevant departments allow time for their personnel to review the documentation, and that they know the seriousness of the review. For successful completion of a documentation project, the reviewers must be available to conduct reviews and to attend review meetings at the time specified in the documentation plan or the review cover letter. (This sample cover letter provides some recommended wording.)

Once reviewer comments have been returned and evaluated, hold a review meeting to ensure the accuracy of the documentation, resolve conflicts between reviewers, and collect final comments.

At the conclusion of the technical review and the review meeting, designated reviewers from each department should "sign off" that the documentation, with the agreed-upon changes, meets with their department's approval.

Comment Acceptance

Comments regarding technical errors in the documentation should be incorporated. Comments regarding technical completeness should be accepted or rejected depending upon the scope and intent of the documentation as specified in the documentation plan or as interpreted by the writer, writing team leader, or manager.

Comments regarding the purpose and scope of the manual, including the intended audience, should be accepted or rejected based upon the related material in the documentation plan.

Comments on editorial style, organization, or cosmetic changes should be accepted or rejected based upon style and design guidelines.

Participants in the Technical Review

Participants in the technical review process should ideally already be members of the project team. However, even those outside the project team (such as customer support personnel and testers) may be able to provide valuable feedback.

Departments you may want to have represented, and their review responsibilities, are listed here. You may want to provide this information (modified for your own situation) as part of the documentation plan.

Product Development
Product Test
Customer Support
Usability Testing
Publications Department

Review Meeting

The review meeting is chaired by the documentation manager or a designated representative. The sign-off reviewers designated in the documentation plan should attend the review meeting. Sign-off reviewers attending the review meeting are responsible for consolidating comments from their area into one copy and for resolving conflicting comments from different reviewers in their area prior to submission.

The writer or writing team leader should prepare an agenda of comment items. In an ideal situation where comments have been collected on line, you can distribute reports before the meeting that list those comments that have been accepted without discussion, those comments that have been rejected, and those comments that are unresolved. Otherwise, mark on the review copies those comments that are unresolved or rejected.

The agenda for the meeting should include rejected comments that reviewers still want to have considered, and unresolved comments.

The chairperson leads a discussion of each item on the agenda. Once the items have been resolved, the sign-off sheet should be distributed for representative signatures.

Often engineers and others feel that their comments regarding organization or writing style should receive as much weight as their comments on technical matters. Keep in mind, and make sure that they keep in mind, that you are the expert on publications, just as they are the experts on coding or testing.