The thing that everyone hates,
but sooner or later we all have to deal with, is writing
documentation. This, however, is not about the art of technical
writing - I'm not going to talk about "tell 'em what
you're going to tell 'em, tell 'em it, then tell 'em what you
told 'em". Instead, this is about what happens after you
write your deathless prose, and how to make it something that
other people will actually use when you're not around.
Back in the early nineties, there
was a short-lived programming fad called "egoless
programming". It took me several years to wrap my head
around it, and I've seen some of its tenets moving into
mainstream development. The core idea was that code should be
reviewed by your peers, who would be expected to criticize it,
and point out flaws and improvements. The expected results of
this were not only better code, but better programmers. I might
note that it was called "egoless" because if you
couldn't let your dearly beloved code go, and accept and make the
recommended changes, your ego got a bruisin'.
As open source became a big
thing, we are, in fact, seeing more and more of this happening as
an expected and normal course of development, and even have it
moving very seriously into the corporate world. In that world, of
course, it's more frequently advocated than actually practiced,
and "we've always done it that way", or "that's not in scope for
this change" will always trump revision.
Some years ago, having
internalized egoless programing to a sufficient degree, I applied
the same idea to documentation. The way I've implemented it is
like this:
-
I write up the best, most
complete document I can, covering everything that I'm aware
of. At the top, in the title information, I mark it very
clearly "draft". This is important, both to
avoid complaints from management, and to give warm fuzzies to
the folks no whose time you are about to impose.
-
Then I print or email copies
to several people, some of whom need to be end users, and the
others technical people who are intimate with what you are
documenting. Then I get down on my knees, and beg them to
rip,. shred, and rend the document, to tell me everything
that I've forgotten to include;
-
where what I've written is incomprehensible;
-
where I've skipped steps, and
-
what's simply incorrect.
-
Now at least half of them, if
they say anything at all, will tell you it's all wonderful,
and they can't offer you any suggestions. These
folks,regardless of how nice they are, or how friendly you
are with them, are useless for this purpose, and you can
probably skip them next time.
-
From the rest, and you may
have to bother them so that they'll get around to it, you'll
get responses ranging from what are minor details to what
will entail major revisions. As you get them, remember that
they are suggestions,
and do not need to be put in as the authors wrote them.
Compare and contrast what you've already written, and start
doing the editing. If you like, make a compromise between
what the criticism suggested and what you want to say -
remember, you are the author, and the last word. Just
make sure that the final result addresses the issue, if it is
a valid one that is in scope of the document. Don't let them
give you criticism that results in scope creep.
-
Once you've gotten all the responses and made the revisions,
go over it thoroughly, at least to catch where you've
cut-and-pasted without fitting it into the rest of the
sentence. Then send copies, marked as draft v. 0.2, or the
revised document to the folks who made the criticisms, and
again beg them for criticism. Try to make sure that you get
all their responses before you start on your next revisions,
though you need to remember that they have other work, and
this is probably not scheduled.
-
When you get their second stage of
criticism and there should be less, unless they've
realized that there was something they forgot to bring up the
first time around, you need to make the changes, and then
walk away from it for a day or so. When you come back to it,
go over the while thing, all the way through, and don't skim.
You will catch typos, grammatical errors, and misstatements.
-
This time, when you get ready to send out copies, make sure
to note that this is a final draft, or v. 0.9, or some such
indicator, so that your reviewers will know that it's nearly
done, and this may be the last time you'll be bothering them
(for this document, at least).
Take in the final criticisms for the final rewrite, and you'll find
that you have a document that is readable, accurate, and usable.
Let me note that by "usable", I mean something that not
only explains something, but that the person who needs to know it
will actually be willing to read, rather than try to find you to
bother.
Going through this process is never "fun" - it's never
enjoyable to have others find fault with your work. On the other
hand, it's all in the development process, rather than producing
a final Work of Art, and then having it chewed up by management.
Then, too, you can get out some of that irritation by bothering
the folks you've asked to give the criticism to actually get
around to it (they'll be putting it off). Even if you do that,
the upshot will be that they'll make sure the document gets used
because they were part of the writing.
In closing, I will note that at least once I've actually gone to
five or six version, first, because I didn't wait for all the
responses, and second, because folks would see the document and
come back to me with yet more stuff that they had forgotten to
mention, was relevant, that no one else knew about, and that I
really did have to add. Even then, the document went official at
about a real v. 0.4, and the rest were 1.x updates.
I hope
this makes the whole process of creating documentation easier. At
the very least, it will spread the pain, and as the old saying
goes, pain shared is pain halved.