Documentation plans, standards manuals, and more

[beverly_robinson -at- datacard -dot- com]

Jessica,

As you're new to the list, you may not know yet that Andrew Plato abhors
standards, structures, and methodologies of any kind, hence his rather flip
reply in the March 30 Techrw-l Digest. I agree with him, to a point. It
often happens that technical writers, being strong on attention to detail,
focus in on minute details and don't see the big picture. BUT, when several
people are working on a project, someone does have to provide a common big
picture so the whole set of user information hangs together.

Of the documents you suggested you want to develop, I think the
documentation plan is the most important. It provides the big picture for
your team of writers and trainers and for the product development team as a
whole. Here are some things to consider putting in the documentation plan:

* A list of user information deliverables
* For each deliverable, some details about how it will be delivered to the
user (will online help be WinHelp, HTML-Help, or something else; will the
User's Guide be hard copy or PDF, page size, number of ink colors, binding;
will training be classroom, web-based, or distributed on CD-ROM; etc.)
* For each deliverable, a statement of the kind of information that will be
included (conceptual, how-to, reference, etc.), possibly a high-level
outline (detailed outlines can come later), and a list of audiences that
will use the deliverable
* For each audience, a description that covers education, computer skills,
and experience with similar products
* If you've been given some requirements for the user information set, a
statement about how each requirement is filled by the proposed plan.
* An estimate of the number of work hours needed to create each
deliverable, and a schedule (including dependencies on the programming
team) for doing the work.

Circulate the plan and get comments from the entire product development
team. If your ideas are 180 degrees off from what the rest of the
development team expected, you can change course immediately, before a lot
of work has to be thrown away. I wouldn't worry too much about what format
the plan takes; the information is more important than whether you use
numbered paragraphs or not.

A good template (and agreement to use it) can replace much of the detail in
the "documentation standard guide" you mentioned. My hope for you is that
your writing and training team members will be reasonable about this. As
far as developing the style, usage, and naming conventions goes, the last
time I was in your situation, we started a list of issues on a shared
document. Once a week we got together and reviewed new items added to the
list and came to agreement on how to handle them.  Here again, being
reasonable and willing to compromise are characteristics you want to
encourage. The style and usage guide grows and develops naturally as you
work on the project. This is much better than trying to think ahead of time
about all the possible situations you *might* run into and gives all team
members a sense of ownership. If they feel they own the guidelines, they're
more likely to follow them than if they're imposed from on high.

I hope this comments are of some use to you.

Beverly Robinson



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems 
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 
Conference East, June 4-5, Baltimore/Washington D.C. area.
http://www.pdfconference.com or toll-free 877/278-2131. 

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.