Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

ajt (2546)

ajt
  (email not shown publicly)
http://www.iredale.net/

UK based. Perl, XML/HTTP, SAP, Debian hacker.

  • CPAN: ATRICKETT [cpan.org]
  • PerlMonks: ajt [perlmonks.org]
  • Local LUG: AdamTrickett [lug.org.uk]
  • Debian Administration: ajt [debian-adm...ration.org]
  • LinkedIn: drajt [linkedin.com]

Journal of ajt (2546)

Wednesday December 28, 2005
01:49 PM

Writing Documentation

[ #28151 ]

Many moons ago on perlmonks I asked: How to write documentation?. I got some answers but overall I was not satisfied with the responses.

This week someone else has asked essentially the same question: creating documentation.

What I can say is that in the time between the two I've worked on a number of projects and you can tell when the documentation is correct.

In one project I created POD in the module and applications based around it and there were also comments in both the Perl and Shell scripts. I also wrote detailed documentation (in plain text) about every aspect of the project, so that it should be possible to reimplement it without me being there. I even wrote man pages for some of the shell installation steps. We tested the documentation when we moved the project into "QA" refinning it as we went. When the project went into production we used the documentation again and it worked like clockwork. When we needed to re-implment the server in an emergency, working from the documentation it worked like clockwork. I know that was good documentation...

Other stuff I've returned to and had no idea what's going on - that's bad documentation.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.