Re: comprehensive documentation

From: Jason Boxman (
Date: 2002-08-29 02:34:40 UTC

On Wednesday 28 August 2002 08:45 pm, Chris Harrington wrote:
> I don't suppose one of your students feels like setting up a PHP server?
> Have any of you ever seen the documentation system over at
> ?

I don't actually have any students in my knowledge. ;) Brian's email and mine are a bit transposed on top of each other.

I've seen the PHP docs. MySQL has something a bit like that, too. Another tack is taken by Perl's POE module, which uses a WiKi, a community run Web site thingy, which anyone can modify, and it keeps history revisions of changes.

I'd still like to see standard documentation backended by DocBook XML, though.

> Granted the scope and subject matter are completely different, but their
> setup allows users to comment ( add to, correct, provide examples etc. )
> on the documentation directly, which means that in the beginning only a
> framework documentation is necessary, the details being provided by the
> community. Certainly a change from the traditional method of a mishmash

That's a nice idea -- as long as a number of people in the community are willing to add and correct additions to the living documentation.

> of websites and lists, but I would think perfect for an effort like
> host_ap which has generated so much interest. Also a great time saver,
> alleviating the requirement for everyone interested to expend the same
> effort ( redundant processes? ) looking around for the information.
> This would certainly translate directly into a dividend in less basic
> questions on the list?

I'd define good documentation as something that satisfies both those requirements. Of course, there will always be someone who'll ask a question that's covered in the manual. :) I've done it myself from time to time.

> -Chris Harrington


Jason Boxman
Administrator TrekWeb.COM - Linux Pages

This archive was generated by hypermail 2.1.4.