Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine

Re: Writing Good Documentation

by tjh (Curate)
on Jun 24, 2002 at 18:25 UTC ( [id://176876] : note . print w/replies, xml ) Need Help??

in reply to Writing Good Documentation

These may look like generalist issues, but they're really a list of gripes I've had about documentation I was trying to depend on, as well as on documentation I've participated in creating :)

  • Carefully choose the viewpoint from which you write. In practice, this means to me that it's important to inspect what you assume from your readers. Who's the audience? etc. In my experience, docs assuming a relatively extreme tech reader usually fails, since no two readers have the same education or experience. It's also dangerous to assume that the author's education is the standard the docs are written to as well.

    Not that I think it should pander to illiterates or uneducated, but I think there are ways to make docs plainly readable, and understandable, for just about everyone.

  • Regardless of the the assumed audience, compose in readable, possibly Reader's Digest style, language. I know that'll get me flamed in some quarters, but docs endure and what's common knowledge or practice now may not be so this time next year.

  • Good overview as a lead, including examples and some various times when the product|module could|would be used.

  • Index thoroughly, including related keywords. If you use jargon others may not understand (now or in the future), they may not find what they need.

  • If the releases are modules or other tools, be very clear in the docs about the params into, and output of, each method or sub.

  • It's irksome to read the docs of modules that are written for a specialty field, and not really be able to quickly discern that. Be sure it's clear almost from the very beginning, what field or other specialty it applies to.

  • Rewrite...rewrite...rewrite

  • Get reviews, just like code reviews.

  • Version the docs as religiously as you version the product.

  • It's ok to have the docs have personality and some personalization. Pronouns are ok...

Have fun!


Replies are listed 'Best First'.
Re: Re: Writing Good Documentation
by vladb (Vicar) on Jun 24, 2002 at 18:57 UTC
    These are all valid points and are generally good to follow. However, one should also look down at how much time has been alotted to documenting your product. In my experience, I was never able to apply all of the above mentioned points completely due to time constraints imposed by various factors (management being one of them ;). Although, documentation is a very important piece, in practice there's not always enough time to finish it off.

    Thus, a few suggestions as to how you might save time all the while produce sufficient documentation.

    • Write your documentation as you move through your project. Project managers sometimes overlook the need for allowing extra time to add documentation to a working code. Most often, they are reluctant to do so when you are all done and the product seems to work just fine (especially in the Web environment, the project is simply closed with too little documentation). However, if you were to ask for a little bit more time during the coding phase (write it off on various factors if you don't really want to disclose the detailed facts), they'll normally give in and thereby provide you with ample room to fit adequate documentation.

    • Write your documentation to look perfect (as much as you possible can) the first time. I know, I know! It is not always possible and I'm nuts for suggesting it, but what I'm saying is at least make it a 'point' to drive at. This will reduce the time you'll have to spend to hack at poorly written/organized documentation.

    • This leads to the next point... Organize your documentation, always! ;). A good documentation outline will normally lead to a well written documentation with minimal time spent writing it.

    # Under Construction
Re: Re: Writing Good Documentation
by rattusillegitimus (Friar) on Jun 24, 2002 at 19:22 UTC
    • Get reviews, just like code reviews.

    This is one of the best ways to be sure your documentation will properly reach its audience. In my experience, it's been best to have at least one person not directly associated with the project review the docs, if possible. Sometimes that's the only way I've realized that one of my assumptions about How The Universe Works is neither common knowledge nor an immutable law of physics. ;)