Article sep2006.tar

Egoless Documentation

Mark Roth

Sooner or later most of us have to write documentation. This article, however, is not about the art of technical writing; it's 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". 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 also better programmers. I might note that it was called "egoless" because if you couldn't let go of your dearly beloved code and accept and make the recommended changes, your ego got a bruisin'.

Some years ago, having internalized egoless programming to a sufficient degree, I applied the same idea to documentation. I've implemented it as follows:

1. 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 very clearly label it "draft". This is important, both to avoid complaints from management and to give warm fuzzies to the folks on whose time you are about to impose.

2. I email copies to several people, some of whom need to be end users and some of whom are technical people intimate with the subject that I'm documenting.

3. Then I beg them to rip, shred, and rend the document, and to tell me:

  • What I've forgotten to include,
  • What 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 won'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, whom you may have to prompt, you'll get responses ranging from what are minor details to what will entail major revisions. As you receive the responses, remember that they are suggestions and do not need to be added exactly as the authors wrote them. Compare and contrast what you've already written and then 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 get to have the last word. Just make sure that the final result addresses the issue as it applies to the documentation and the project. Don't let them give you criticism that results in scope creep.

4. Once you've gotten all the responses and made the revisions, review the document thoroughly. Then send copies, marked as draft v. 0.2, of the revised document to the folks who made the criticisms, and beg them for more comments. 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.

5. When you receive the second round of criticism -- and there should be fewer remarks this time -- you need to make those changes. Then, I suggest you walk away from it for a day or so. When you come back to the document, read the whole thing, all the way through, and don't skim. This way you will catch typos, grammatical errors, and misstatements.

6. The next time you 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).

7. Once you have incorporated the final criticisms in the final version, you'll find that you have a document that is readable, accurate, and usable. Note that by "usable", I mean a document that not only explains something, but that the user will actually be willing to read.

Going through this process is not fun; it's never enjoyable to have others find fault with your work. On the other hand, remember that it's all a development process, and it's better than producing a final Work of Art just to have it chewed up by management. The upshot of including others in the documentation is that they'll make sure the document gets used because they had a stake in the creative process.

In closing, I will note that at least once I've generated five or six versions of a document. This happened, first, because I didn't wait for all the responses, and second, because folks kept coming back to me with yet more stuff that they had forgotten to mention, that was relevant, that no one else knew about, and that I really did need to add. Even then, the document went official at about a real v. 0.4, and the rest were 1.x updates.

I hope these few tips make the whole process of creating documentation easier for you. At the very least, it will spread the pain, and as the old saying goes, pain shared is pain halved.

Mark has been a computer professional in Unix, DOS & Windows, and mainframes for more than two dozen years. He doesn't actually willingly do documentation.