G'day ajt,

It sounds like you're already got a great start with the whole documentation thing. The following isn't really advice, it's more a relating of my own experience and what's worked for me.

User Documentation
I've tended to prefer to use a version management system such as CVS rather than making hard-copies at every stage. With CVS it's very easy to see the difference between versions, to track who made which changes and when, and to maintain multiple branches of the software if necessary. Of course, CVS does have a bit of a learning curve, and non-technical people take quite some time to get used to it, even with a graphical interface.

For user documentation, I've found the best way is to get a user to write it. Seriously. There'll be things which neither yourself nor your fellow developers will think to document, simply because they're so obvious you'll never think of them. I've been at workplaces where the user documentation was always written by non-technical people for that very reason.

Documentation is like software in many ways, in that it also needs to be tested. The best people to test are those who aren't already familiar with the software, and haven't had you drop a previous copy of the user manual on their desk. I always exist my test population much too quickly. ;)

Technical Documentation
For technical documentation, find a document that you find really useful, and copy the layout. POD is fabulous for tech docs because you can have the documentation sitting next to the code it refers too -- nobody can lose the documentation or be too busy to look it up.

I try to document every function -- what it's purpose is, an y bugs or unexpected behaviour it might have, and an example of use if it's not immediately obvious. Good, clean code is often self-documenting, and that's certainly something worth aiming for.

Each file should also (at a minimum) have some header documentation stating the purpose of the file, when it was written, and who by. This means someone can quickly and easily find if they're in the right place without having to look at code.

Keeping an FAQ is also very useful. Usually the same questions keep appearing again and again. These are obviously things you want to document.

Cheers,
Paul

In reply to Re: How to write documentation? by pjf
in thread How to write documentation? by ajt

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.