Home Company CPI Documentation Process

CPI Documentation Process

Cambridge Publications' diverse set of clients face a broad range of business situations, documentation requirements, and knowledge transfer goals. To meet these needs, CPI develops documentation and related materials on a project basis, using a comprehensive documentation methodology that we have developed and refined over the last ten years. The CPI documentation methodology provides structure, consistency, and predictable project planning, resulting in shorter project cycle times, higher work quality, increased project predictability, and lower costs than would otherwise be possible.

A successful documentation project:

• Meets the business and technical needs of the client
• Responds to and resolves the identified documentation issues
• Proceeds through to final delivery without undue difficulty or unexpected problems

The CPI documentation methodology produces these results.

Documentation Methodology Phases

The CPI documentation methodology uses a four-phase approach to describe the development of documentation and related projects. The methodology represents an end-to-end solution, starting with the analysis of customer requirements and continuing until final delivery of completed work to the client.

Process Phases and Stages

Discover

As the first step, CPI learns about the client's project, what the deliverable needs to include, and what it needs to achieve. CPI gathers information about business issues-for example, product goals and strategies, marketing and channel plans-and technical issues, which include specific details about the product being documented and any specialized technical skills the project will require.

The information acquired during the Discover phase provides the background against which CPI can build a detailed project plan-one that ensures the creation of a high-quality deliverable on time and within budget.

The Discover phase includes these stages:

• Explore customer requirements
• Analyze gathered information
• Create project plan

Explore Customer Requirements

The Explore customer requirements stage provides an opportunity for CPI to learn about the business and technical issues that will impact the documentation to be created. CPI gathers information by reviewing existing documentation, examining the product itself, and interviewing stakeholders and subject matter experts identified by the customer.

Analyze Gathered Information

During the Analyze gathered information stage, CPI analyzes the raw data captured in the Explore customer requirements stage to gain a more complete understanding of the product or process to be documented. At this time we also identify specific client requirements (for example, a schedule that cannot be modified, or unusual technical skills that might be necessary to complete the project) and other factors that will impact how the documentation is created and delivered.

Create Project Plan

CPI uses the information gathered and analyzed in the first two stages of the Discover phase to create a detailed project plan. The project plan describes both the deliverable and the project process in considerable detail. As a roadmap for completing the project, the project plan generally contains these elements:

• Description of the deliverable. Some examples: "A web-based user's guide for an Internet application," "A paper-based tutorial for novice users," "A help--based reference guide for a complex development tool."
• Size or length of the deliverable. In the case of a book, length is described by page count; help systems or web sites use number of topics as the metric.
• Specific resources, skill sets, and staffing levels that may be required to complete the project successfully.
• Detailed schedule, showing all steps and milestones required to take the project from start to conclusion.
• Project workflow description, which presents an overview of the project development process. The workflow highlights and describes milestones, milestone-related issues, and specific obligations (such as work reviews and meetings) that affect both CPI and the client.

A solid project plan provides an essential tool for ensuring that the project proceeds according to the expectations of both the client and CPI. In CPI's experience, the presence of a well-prepared project plan is a key determinant of project success.

Model

The Model phase details how the deliverables specified during the Discover phase will be constructed. In this phase, CPI develops and the client approves the outlines and organizational structure around which content will be developed during the remainder of the project. CPI writes and the client approves a representative sample of content. These elements assembled in the Model form the foundation on which successful and efficient completion of the entire project rests.

At the conclusion of this phase, both CPI and the client understand how the documentation will be organized and what the overall length of the completed work product will be. The Model phase consists of these stages:

• Develop high-level outline
• Develop detailed outline
• Create sample

Develop High-level Outline

This stage is used to identify and describe the major components of the deliverable:

• For a book, the high-level outline identifies and briefly describes parts, chapters, and chapter sections.
• For a help system, the high-level outline identifies and briefly describes topics and specifies a sequence for them.
• The high-level provides an overview of the structure of the book, help system, or web site being developed.

Develop Detailed Outline

Following client approval of the high-level outline, the project team creates a detailed outline. The detailed outline breaks the broad topics into narrower ones, expanding the depth and sharpening the focus for each topic covered, and so builds on the base created in the high-level outline.

The detailed outline adds the following information to the high-level outline:

• A brief description of each section of the final product. The descriptions state what each section of the outline will cover and if appropriate, the relationship of that section to the one before or the one after.
• Page counts for each section of the final product.
• Page counts play a central role in helping quantify schedule, resource, and cost requirements for most documentation, help, and web projects. Higher page counts are often associated with higher costs and longer schedules. For this reason, the detailed outline is an essential tool in avoiding unexpected page count increases during the life of the project.
• The project manager uses the detailed outline as a tool to monitor the work process from both project management and content development perspectives.

Create sample

After the detailed outline has been approved by the client, CPI writers select a representative section of the detailed outline and expand it into a full written sample. The sample shows the client how the content will be treated and demonstrates the level of detail that will be included when the first draft is written. Together with the detailed outline, the sample section provides the client with a preview of the completed project, including the writing style and tone and the overall level of detail included in the text.

Build

At this point, CPI has presented and the client has accepted a project plan, detailed outline, and writing sample; CPI and the client are in agreement regarding fundamental aspects of both the project process and the final deliverable. With this alignment between the client and CPI firmly in place, writing can move forward quickly. During the Build phase, CPI creates what will ultimately become the documentation deliverable.

There are three stages in the Build phase:

• Develop template
• Write first draft
• Write second draft

Develop template

In the Develop template stage, a template that governs the look and feel of the final deliverable is created. This template, which is in many respects similar to a set of detailed designer's specifications, defines all the information elements that the deliverable will contain-specifying every detail, for example, of headings, paragraphs, and sections.

The task of creating the template is the responsibility of the production manager, as the template definition process involves translating editorial and graphical specifications into whatever production tool will be used to create the final deliverable. In the case of a manual, the template is created using a tool such as Microsoft Word or FrameMaker. For electronic documentation delivery, the template is typically built using HTML, WinHelp, or HTML Help.

The project manager reviews the template to ensure that it includes all the information elements specified in the Design phase. When the project manager has approved the template, he or she disseminates it to the writers so that they can write within it. Providing the template to the content developers early in the writing process reduces formatting time later in the project.

Write first draft

Documentation is written in drafts, each of which is more refined and complete than the previous one. The Write first draft stage results in the creation of a complete first version of the content. This draft covers all topics included in the detailed outline. Unlike the final deliverable, however, the first draft:

• May not include graphics
• Will indicate, but not be linked to cross-references
• Will probably contain questions to reviewers and subject matter experts
• May contain other interim notes

Screen captures, diagrams, and other artwork are specified in the text by the writer (perhaps accompanied by rough sketches, in the case of drawings), giving reviewers the opportunity to modify artwork instructions, but avoiding the wasted time and expense that would result from the creation of incorrect or unnecessary artwork.

The project plan generally includes a schedule of the workflow for creating and submitting the first draft to the client. If a project is large, the first draft may be submitted in batches, to make the review process easier for the client; for smaller projects, the first draft is typically submitted to the client as a single whole.

Prior to handing review drafts to the client, CPI conducts its own internal review of the work. When the project manager is satisfied that the work meets CPI's internal quality standards for first-draft review, he or she submits the draft to the client for comments and corrections. CPI provides review guidelines to help the client review the draft efficiently. Often, a review meeting is held between the client and CPI, to provide an opportunity for discussion and explanation of the review comments.

Write second draft

Following the review meeting, the reviewed first draft is returned to CPI for incorporation of the client's comments. The writers implement the client's comments and corrections, creating a second draft, which also includes screen captures and other artwork. The goal of the Write second draft stage is to create a draft in which all comments and corrections have been implemented—a draft that is ready to be taken through the production process. After the CPI project manager reviews the second draft to ensure that it passes CPI's internal quality checks, the new draft is handed to the client for a second draft review.

The client reviews the second draft, verifying that requested changes have been made and checking for obvious formatting errors. At this point in the project process, there should be few, if any, changes to content unless there have been changes to the product being documented. If there have been such changes, the second draft review will indicate modifications required to bring the content into conformity with the current state of the product.

Once the client has reviewed and approved the second draft, CPI moves the work into final production.

Deliver

With the completion of the second draft-a major milestone toward completion of the final project deliverable-most content has been written and approved by the client. Now the content must be put into final form for delivery. The Deliver phase covers the steps required to create an end-product for the client.

The Deliver phase consists of these stages:

• File preparation
• Editorial processing
• Final production
• Delivery to client

File preparation

The File preparation stage involves preparing the second draft to be put through production. If the deliverable is a web site or help system, the CPI production group compiles topics into a web- or help-based product. If the deliverable is a manual, all content source files must be combined into book form.

Whether web site, help system, or book, a variety of steps must be performed to prepare the document for the final production process. These steps include generating a table of contents and index, inserting screen captures, executing any edits to artwork, and implementing cross-references.

Editorial processing

The Editorial processing stage represents a set of quality control reviews and measures designed to ensure that the content is error-free. CPI's editorial group checks the text for grammar, logic, and formatting consistency. Generally, there should be few relatively few corrections, since the content has been through two content reviews at earlier steps in the process. Nonetheless, documentation best practices dictate that the text receive thorough editing and proofreading at this stage.

Another important step in the Editorial processing stage is creating an index for the book or help system. After the index has been created, production staff check it for consistency and redundancy—the duplication of entries caused by variations in spelling or capitalization.

Final production

The Final production stage is the last step in the process of creating the deliverable.
To create the final product, CPI incorporates changes that result from the quality reviews that take place during the Editorial processing stage and then performs the final production steps:
For a web site or help system, final production steps include compiling the deliverable into a set of topics and files, testing links, and proofreading the index.

For a book, final production steps include creating files appropriate for electronic document distribution and/or paper printing and binding.

Finally, all cross-references are verified, the text is proofread, and the deliverable is checked to ensure that it is indeed ready for presentation to the client.

Delivery to client

Once all checks have been performed and the project manager provides authorization, the completed project is delivered to the client.