Re: Ratio of Programmers (or Manuals) to Writers in Software Documentation

[Robert Plamondon <robert -at- PLAMONDON -dot- COM>]

>I'm a little puzzeled as to why the number of writers is necessarily tied
>to the number of developers, (as opposed to the amount/type of material to
>be written).

Nothing's hard-and-fast in this business.  Well, a few things:

* You won't get review copies back on time without the implicit threat
  of publicly shaming the latecomers.

* Engineers will convince themselves that they can do a project in half
  the time they really can, sign up for it, and then blame Marketing
  when everything blows up in their faces. Again.

* Sales wants stuff NOW, until they read it, at which point they insist
  that they never, ever dropped so much as the tiniest hint that you
  should slap something together so they could go out and sell the product.

But besides THAT, there aren't any hard-and-fast rules.  The idea that
there should be, say, one writer per developer in general-market application
software (such as spreadsheets) is an attempt by non-writers to quantify
the relative work in creating vs. documenting a product.

Of course, reality is more messy than that.  A really elegant product
with strong internal logic barely needs external documentation at all,
any more than you need read a manual to operate a bathroom sink.  A
putrid, horrifying product, designed without logic or theme, requires
a massive amount of documentation, which still doesn't solve the basic
problem.  It's like trying to wallpaper a cracked and broken plaster
wall instead of fixing it.  After massive amounts of effort and the
expenditure of a lot of paper, you've still got something ugly and
broken, which should have been fixed FIRST.

I have heard the one-to-one ratio several times over the last ten years,
always for consumer software.  OEM software, in which the end-user is
an engineer or technician, usually gets much rougher documentation,
and the ratio of developers to writers can be spun out indefinitely.
Since, in OEM work, the subject matter is often obscure to people without
formal technical training, it's more traditional for the engineers to
serve as authors, and the "technical writers" to serve as technical
editors.  This is perfectly appropriate, and can lead to top-notch
documentation with a motivated engineering team (and such things DO
exist), since an editor can handle a lot more volume than a writer --
about 25 times more, by one oft-quoted metric (1 page per man-day
for writing, 25 pages per man-day for technical editing).

That probably establishes the boundaries for staffing:  one tech writer
per developer in very customer-oriented consumer product documentation,
and as few as one editor per 25 developers for rocket-scientist OEM
work.  In the latter case, the editor has to walk on water AND have
a committed engineering staff, or the documetation will suffer.  Usually,
at least one element is lacking, and the documentation suffers quite
a bit.

(Of course, if the developers aren't producing much of anything,
the publications staff can be cut back further, because there's little
to document.)

I'm not counting production staff (illustrators, desktop publishers)
because, in the 1:1 case, there are plenty of bodies around to take
care of these chores (plus a lot of money for specialists on a contract
basis, no doubt), and, in the 25:1 case, the company will instantly
devolve into the "no diagrams anywhere" style of software documentation,
leaving only a trivial formatting and layout job, which can be done
by anybody.

        -- Robert
--
Robert Plamondon * Writer * robert -at- plamondon -dot- com * (408) 321-8771
4271 North First Street, #106 * San Jose * California * 95134-1215
   "Writing is like plumbing -- even people who know how to do it will
    pay top dollar to keep their hands clean."