Re: Documentation plan?

[Brad Mehlenbacher <brad_m -at- UNITY -dot- NCSU -dot- EDU>]

Terrific summary of the myriad of "details" that go into devising a
documentation plan (suite), Len! To be a bit of a trouble-maker, I'd add
three things to the discussion:

1. Most technical communicators never _really_ talk to or even meet,
in fact, the audience for their documents, something that reveals our
lack of commitment to defining the audience, purpose, and goals of our
documentation.

2. Defining just what the differences are between an effective user's
guide, reference material, troubleshooting text, quick reference card,
online help system, documentation, or hypertext/media is still very much
open to debate (although most such 'documents' are still woefully
feature-based versus task-oriented).

3. Lucy Suchman, out at Xerox Parc, has written an excellent book ("Plans
and Situated Actions: The Problem of Machine Communication," 1988) that's
very relevant to this discussion. In it, she argues persuasively that
plans are never complete, flawless, or accurate. Humans don't work that
way; rather, plans (whether they're for software design or documents) are
constantly open to revision, re-iteration, review. In this sense, all
documentation plans are, from the outset, doomed to (relative) failure.

Cheers, Brad.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
>> Brad Mehlenbacher         Phone:     (919) 515-4138           <<
>> Assistant Professor       Fax:       (919) 515-7856           <<
>> Technical Communication                                       <<
>>                           E-mail:    brad_m -at- unity -dot- ncsu -dot- edu    <<
>> English Department                                            <<
>> NC State University    "An academic is someone naive enough   <<
>> Raleigh, NC 27695-8105  to beg downsized companies for money" <<
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

> > What is a documentation plan? (I've been looking at job ads,
> > and some of them require the ability to make one of these.)
> >
> > Karen Kay
> >   karenk -at- netcom -dot- com

> When you write on a project, you do it from a plan. Everybody takes a
> shot at it before you start writing, so you don't leave out stuff you
> should include or include stuff you should leave out.

> Doc plans vary from place to place, but most of them I've seen include
> some standard information, like

> -       the name of the book
> -       the audience, purpose and scope of the book
> -       the approach (standard reference, usage, tutorial, examples,
>         etc.
> -       implementation details; typographical style, document design,
>         how many pages, how many figures, how many screens, online or
>         not, code in the book, how many reviews, color or b&w, tools and
>         equipement and software resources required, etc.
> -       project team; manager, writers, reviewers, editors, and so on,
>         who's who, who is responsible for what
> -       proposed content outline (sometimes wi/ page count, people
>         responsible)
> -       schedule; all milestones with dates
> -       time or money budget; time and materials; etc.

> What a particular outfit wants depends on how it operates, but these are
> the essentials. There's a knack to coming up with good estimates for a
> plan; experience counts, but you can wing it. If you work as a
> contractor, though, you better be close.

> Hope this helps. What all do other list members put in their plans?  I'd
> be interested, too...

> |Len Olszewski, Technical Writer | "Hardcopy is the ultimate backup!" |
> |saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA|   -John Sanders                    |
> |---------------------------------------------------------------------|
> | Opinions this ludicrous are mine. Reasonable opinions will cost you.|