A doc plan template (Karen)

[lpraderio -at- CLIFF -dot- WHOI -dot- EDU]

Hi Karen,

I have a doc plan template that I use that you can use if you like.  It's
actually a rewrite and expansion of a doc plan that MIT used to use.  I got
theirs and with permission revamped it.  It was necessary to expand it because
the group I was working for had never seen one and needed to know what each
section would contain.  If anyone has any comments for change, please let me
know.

It has three sections addressing the product/service, document, and costs.
Each subsection explains what the doc plan writer is supposed to fill in.  I
use it now and again, but really only offer 1-2 lines/subsection so it's now
more of a doc memo with a table of contents for the doc/project attached.  In
fact, some parts I don't need to use, so it's not more than 2-3 pages these
days.  I've included the ascii version below.  If you use it, please let me
know, and if you pass it on to others please do so with the stipulation that
it's FREE and no one can use it to extract a fee.

Laura Praderio
Woods Hole Oceanographic Institution
lpraderio -at- whoi -dot- edu

******************************************

Doc Plan Template
Contact:  Laura Praderio
Technical Writer/Editor
Woods Hole Oceanographic Institution
Clark 154
Woods Hole, MA  02543
lpraderio -at- whoi -dot- edu

Copyright.  1991.  Woods Hole Oceanographic Institution.  This doc plan
template is a rewrite, with permission, from a doc plan template created by
MIT.  It is FREE for distribution and use; no fee may be accepted for its
distribution and/or use.  (Please let me know if you use it, I'm just curious
about how people would apply it.  Please note that the copyright and date are
included so that no one can use this template for commercial gain.)


***********************************

                        Title of Sample Documentation Plan
                        ----------------------------------


To:  Some person or client
From:  Writer
Date:  Day/Month/Year
Subject:  Create or revise a document, include version if revising.
(ISC 91-293, This is a WHOI internal number for tracking the template.)

cc:  People involved with the documentation



                        Service/Project Section
                        -----------------------

(This section describes the service or project that requires the document and
designates the documentation team.  List alternative methods and people in the
appropriate areas, if possible, to ensure that no one step halts the production
of the document.)


Document and Service/Project

Propose to write or revise a specific type of document for a group/client that
provides a particular service/product to a computing community or a client.
Include the document in a specific area of documentation with a document number.


Management Goals

Describe what management expects this service/product to do and what they
expect the document to do.  This area proves that the writer understands what
management expects from this service and document.


Service/Project Goals

Give an overview of the service/project/product.  Describe what the service is,
how it works (explain various parts or procedures), what it should do, who can
use it, what aspect of it computer users or clients will use (interface), the
costs to use it, and explain future changes.  This area shows that the writer,
who must document the service, really knows it.


Document Approach

Describe what features should be emphasized in the document.  Explain what
makes this document different and necessary as compared to the last version.
Include the revision history of the document, so that anyone can track changes.
Project document updates, and explain how any changes in the service in one
year will affect the document.  List priorities for updating, will the writer
need to create a new document, rewrite the existing one, or just make a few
changes.  This area gives the writer an idea of the life of the document and
projected changes.


Documentation Team

The team may consists of a project manager, service/product contact, writer,
editor, graphics person, and alpha and beta testers.  Include breakdown of
costs after each section if required.

Project Manager.  Have a project manager for the documentation team.  The
project manger should designate the writer(s), editors, and alpha and beta
testers in the documentation team and be responsible for maintaining contacts
with each person.  A project manager should let editors know to what degree
they should edit a document, and request a deadline.  The project manager may
or may not be responsible for writing the document, but will always edit the
drafts and will have the final say over the content and production of the
document.  Cost:  .

Service Contact.  Estimate when the service person, who is responsible for
implementing the application/utility/program, will have the final version so
that the writer can begin to document it.  This person should be available for
questions from the writer.  Cost:  .

Writer.  Designate this person and, if possible, an alternate.  The writer's
involvement should begin in the design phase, but can begin when beta testing
the service.  The writer should have a final version of the document after the
service/product is complete, not in the testing stages when the service and,
therefore, document could require more revision.   Cost:  .

Editors.  Designate a content editors to verify the contents of the document.
They should be people who are familiar with the service.  Use two to three
editors to maximize the accuracy of the contents.  Content editors should query
the content and language usage associated with the service.  They should not
rewrite the document or change the author's individual style.  Designate a
technical editor who can review the document's grammar, syntax, and structure.
This is primarily a language editor who can also query content.  Editors are
required to sign-off on any document they edit.  Cost:  .

Graphics Person.  Designate who is responsible for producing any graphics in
the document.  Cost:  .

Alpha and Beta Testers.  Designate three or more people each to perform alpha
and beta testing. State why you think they'd be good reviewers:  Are they
novices?  Does their expertise level match the level the document addresses?
Make sure the reviewers want to be on the list.  List two or three alternates.
Politely write down what you expect them to do and what feedback you need.  Let
them know where, when, how long, and on what platform they will perform the
test.  Make a decision if you want to quietly sit by their side, without
helping them, when they test the document, or prefer to be absent during
testing.  Writers should note frustrations, stumbling blocks in the
documentation, and areas that instruct well.  Cost:  .


Resources

There are resources for the writer to use when producing the document.
Resources can pertain to space and work:  a suitable environment to write,
hopefully quiet.  Minimize interruptions, prioritize this project with other
work.  Breakdown costs at end of each subsection if required.

Information resources can be any other documents that the writer needs to refer
users to or use him or herself.  They can include written manuals, documents,
flyers, and brochures; written or on-line files and help, tutorials, messages,
and databases.  Explain how the writer can gain access to these resources.
This area proves that the writer has the correct environment to get the work
done and knows of available information sources.  (If you want to be
successful, put yourself in an environment to be successful.)


Schedule

There are writing and editing standards in industry that the writer can use to
estimate the schedule.  Make a time-line that includes the schedule of the
project manager, service contact (if applicable), writer, editors, and testers.
Include time for the writer to learn the service, meetings, writing, editing,
adding edits, reformatting, travel time, and any other relevant items.  Make a
note in the schedule that references dependencies (see below), which may affect
the schedule.  If there are any changes in the schedule, notify the project
manager immediately.

Writing Standards.  A writer can produce two, double-spaced pages of text each
day, including research.

Editing Standards.  An editor can edit 8-10, double-spaced pages per hour of
first draft for light, technical editing, and three to five pages per hour for
content and technical editing (This does not include incorporating edits.).  An
editor can rewrite 2-3 pages per hour (This does not include incorporating
edits.).  Any edits after the first pass take one quarter the time.


Dependencies

These are issues that the project manager should be made aware of that may
affect the outcome of the document.  If possible, list alternatives to have a
secondary plan of action.  Here are a few points to consider:  Is the service
or product the finalized version?  Does the person installing or developing the
service need more time?  What time does the service person need to help the
writer learn the service ?  What if a member of the documentation team is no
longer able to help?  Will you need additional staffing?  Is there accurate and
speedy communication of service changes to the writer?  Did the writer project
accurate and timely deadlines for drafts and tests?  Will the reviews be
accurate and timely?  Is the writer trying to write about something that keeps
changing?  Are there any peripheral services or projects that affect the
outcome of your service (will it be delayed)?  Does the release date of the
service provide enough time to complete documentation?



                            Document Section
                            ----------------

(This section outlines the document and shows where it fits within the current
documentation.  Attach a table of contents to this doc plan.)


Standards

There are several standards that the client/group may already use to create its
documents.  Writers and technical editors should use them to keep the documents
consistent.  Pick a dictionary and style guide if not already stated.


Outline of Proposed Document

New Title.  Give new, full title of document.  For reference include old title
and any other titles it is commonly called.

Area of Documentation.  Cite current doc set or state new one.

Document Number.  Give it a number.  For a revised document confirm the number
and revision date with the project manager.

Audience Description.  Describe who will use the document.  Include the
audiences' level of (computer) expertise and their background experiences (from
what fields).  Define the user's tasks:  What they have to do to use the
document and the service (any assumptions); then, outline how to reach the
audience to find out their needs concerning the document.  For example, will
the writer use interviews, put him or herself in the user's shoes and try the
service, sit with a new user and note their work and/or past experience?  Don't
assume the users know what level you are working at or writing on - you, the
writer, have to find out what level of explanation the users need and work from
there.  Make sure that the end user will find the document usable by using
alpha and beta tests.  This area makes sure that the writer understands who the
audience is and what level of expertise the document needs to address.

Purpose.  Explain the purpose of the document and what the user expects it to
show them.

Format/Design.  Use the established format for documents or if the document
does not fit that format and needs to be designed differently to be more
effective, then designate who will do the design.  (Include a mockup, a rough
drawing/draft of the design.  Don't go overboard on time here, just give blocks
and titles and headers on a page.  The design is going to change somewhat and
state this clearly.)

Content Description.  Organize the document sequentially or chronologically,
move from general to specific information or however to create a deductive
framework.  Include a table of contents with this doc plan.  Here are a few
examples of areas within a document.

Title Page:  user's guides, tutorials, reference manuals, and lengthy handouts
may have a title page.  Smaller handouts and quick references may have a title
in a nameplate on the top of the page.
Table of Contents:  list headers for chapters, sections, and subsections.  In
shorter documents, less than three chapters, be very descriptive in the main
table of contents so that there is no need for chapter tables of contents.
Chapter cover page:  give a title and short description of each chapter.  Try
to include key concepts that will be sections.
Glossary:  defines terms and concepts.
Index:  reference all headers in text, and key terms and concepts with page
numbers.
Appendixes and More Information.

Page Estimate.  Estimate number of pages for entire document

Hours Estimate (optional if giving lump sum estimate).  Estimate four times the
page estimate to see how many hours it will take to write the document  (I like
to have twice as long and show it as a maximum number of hours because the
stuff I document is invariably changing.)



                            Costs Section
                            ------------------

(This section describes the costs to produce the document. You will probably
have to revamp this section for your cost structure as it may not reflect your
situation accurately.)



Costs

Equipment. Software, hardware, printers (optional depending on who provides it).
Printing.  Drafts and final.
Misc.  List paper, disks, etc.
Training
Testing
Travel
Distribution
Personnel.  Writer, editor, etc.
Headaches

Payment Process.  Define.



                Signatures for Documentation Plan
                ---------------------------------

(At my organization, we don't have formal contracts so you will probably need
to revamp this section as necessary.)


------------------------        ------------------------
Project Manager     Date        Editor              Date


------------------------        ------------------------

Writer          Date            Client              Date


------------------------
Editor              Date