This section walks you through the process of planning and writing documentation and of getting it reviewed.
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.
------------------------------------------------------------------------------------
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.
-------------------------------------------------------------------------------------------
Topic Content
-------------------------------------------------------------------------------------------
Product Product name and version, brief description of the product's
information intended use.
Documentation Personnel, equipment.
resource
requirements
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.
objectives
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
include:
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
-------------------------------------------------------------------------------------------
Documentation concerns especially affect product development at two points in the schedule: during technical review and at the end of the project.
This section deals with the writing of the documentation and with the handoffs the writer must deliver.
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:
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:
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."
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.
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.
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.
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.
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 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.
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.