Early on in my career, I wrote a great deal of docs & was responsible for getting
the coders to document their stuff. Here's what I found works:
1. Internal code docs: make it a requirement that interfaces and subroutine
behavior are documented. Enforce this with code review (which is a great idea
anyway). File noncritical bugs against undocumented code. Do this enthusiastically,
and eventually your coders will expect to see good docs in their fellows' code.
Tools: freeform embedded docs are OK here; they're only read by programmers.
If your group has a code style policy, add a doc style to it.
2. Programmer docs: it takes a programmer to write docs for programmers,
and the internal code docs mentioned above won't cut it when you need to create
an API manual. Instead, you'll either have to be lucky (or medieval) enough
to find (or force) a programmer to generate the docs, or you will have to train
up a tech writer to be a programmer. The latter is slower, but overall more
effective.
Tools: Programmers read docs while writing code, so that means paper
output or docs they can view in or near their code editor. Plain HTML is surprisingly
poor for reference docs, but if you add effective searching & automatic crossrefs,
it's OK (see the online Apache docs
for example).
I like creating docs in FrameMaker
(from Adobe) since it outputs serviceable HTML w/indices, graphics, & crossrefs,
has an excellent WYSIWYG editor, gracefully handles massive documents up to
encyclopedia size, prints books well, is available on Win/Mac/UNIXen, and (very
important) stores files in a diff-able (plays well with CVS) format.
3. End user docs. These are best written by a tech writer who's also
a power user. You'll find that most programmers are not power users; they know
their own bit of the system extremely well, but bupkus about the rest and often
aren't really interested in using the whole product for which they're coding.
Make sure the people selling/promoting the product review end-user docs, too.
4. File bugs against docs. This has been mentioned elsewhere, but it
bears repeating: treat errors and missing features in your docs at least as
rigorously as you treat code bugs. Make sure the support folks can and do file
bugs; they're the people who hear about the bugs after release.
Tools: gnats is the
bomb: simple, cheap, modifiable, works anywhere. Make a doc-bug category that
your writers manage.
5. Put tech writers on the engineering team. Many organizations think
docs are sales materials or something, so they put the writers in the sales,
marketing, or support department. This makes for bad docs. Instead, tech writers
should work next to and at the pace of coders. Ideally, doc writing starts as
soon as the design phase completes. (You do have a design phase, right?)
Good in-progress docs are an excellent roadmap for the coders, and result in
the docs & code converging on completion at the same time.
6. Hire or grow professional writers. Pretty much anyone who speaks
the language can write good docs, but only people who like writing will stick
to it through ten releases. Personally, I didn't know I liked writing until
someone hired me to do it. Presto, professional writer!
