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 ]

Matts (1087)

Matts
  (email not shown publicly)

I work for MessageLabs [messagelabs.com] in Toronto, ON, Canada. I write spam filters, MTA software, high performance network software, string matching algorithms, and other cool stuff mostly in Perl and C.

Journal of Matts (1087)

Sunday November 30, 2003
05:56 PM

On Documenting Projects

[ #16087 ]

From a recent discussion on p5p:

As someone who wrote a lot of docs in the last 5 years, if you will allow me to give you an advice, it's really easy to improve docs incrementally by just watching discussions on this list, beginners list, perlmonks.org and any other lists that you are hanging on, and post patches based on the threads that won't have been started if the docs were there, and fixing the gaps by making summaries of those threads and posting them here as patches to .pod files. Notice that you don't even have to participate in those threads, all you need is to be a good librarian.

The majority of the mod_perl 1.0 guide (http://perl.apache.org/docs/1.0/guide/) which is more than 1000pp worth of docs, was written just like that. People asked questions on the list, gurus have answered them, someone has summarized those threads and added them to the docs, so the broken records effect won't repeat again. It worked and still works perfectly for us, and you can do the same.

Take it in baby steps and you will get far...

Many times I don't have the time to write summaries, so I mark candidate threads as something that I'd like to be documented. and hopefully come back to them later. In fact I've a whole lot of docs to write, based on the recent input from TomC and NI-S about the intricacies of the IO stuff. I hope I'll catch up with those soonish.

Finally, it's being a good example that you are after, not volunteers. You want to be an example to other potential contributors. When people see that someone does a great job contributing, they want to do the same (who am I kidding ;).

This post was by Stas Beckman, who has English as a second language, who has arguably written very good extensive documentation for mod_perl, and is an example to us all for his dedication and commitment.

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.