Just a couple of short points.

First up: use your own documentation.
Try and use every feature as you've described it in the docs - I find I sometimes miss a piece of functionality in the docs (or even the code) if I'm in a hurry.
Have your colleagues/friends use the code using only the documentation, not verbal tips :-)

Depending on the complexity of the system (and the skill of the document's author), I've also found that a number of increasingly more detailed sections can be of great help. I don't want to have to read the whole 100 pages of the document to know how enough about how the system works to begin to follow it.
Good diagrams can also help - a picture says a thousand words...

As already mentioned, good examples are one of the most useful pieces of the whole document.
Showing how to solve the problem the code was written for using an example or two can make sense of several pages of more in-depth options, methods or sub-commands.

Update: Oh, and if no-one ever uses the docs, best find out why: either you have built the best piece of software ever, or the docs are rubbish :-)

BazB

In reply to Re: Writing Good Documentation by BazB
in thread Writing Good Documentation by defyance

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.