Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
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.


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

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

  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or or How to display code and escape characters are good places to start.
Log In?

What's my password?
Create A New User
Domain Nodelet?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others meditating upon the Monastery: (3)
As of 2021-11-28 06:14 GMT
Find Nodes?
    Voting Booth?

    No recent polls found