discuss: Linux documentation
Subject:
Re: [discuss] Linux documentation
From:
"Dan Scott" ####@####.####
Date:
23 Sep 2007 02:25:49 +0000
Message-Id: <fbb0d11d0709221925v6ee52220x998a972e21c54f01@mail.gmail.com>
On 14/09/2007, jdd ####@####.#### wrote:
> Sam Varshavchik wrote:
> > Steven writes:
> >
> >> How are the html man pages going ? (have i missed some news ?) Hmmm...
> >> the idea
> >> is nice, but maybe not so worthwhile considering the poor state of
> >> Linux man
> >> pages in general.
> >
> > They're doing just fine, thank you for asking. Besides the core man
> > pages set, I also have coreutils, util-linux, gnutls, openldap,
> > linuxpam, SDL, and PCRE man pages, as nicely-rendered HTML.
> >
> > http://www.tldp.org/manpages/man-html/
> >
> >
>
> I know this is an old discussion, but may be it's time to make changes.
>
> I wonder how all this doc is used. I know I don't use it anymore or
> nearly.
>
> I noticed that the php documentation is very nice and use a system
> similar to a wiki (I don't know exactly what system, but this should
> be easy to find)
>
> That is the documentation (online) is irganised as usual, but at the
> and of each page there is a user part where everybody (don't know if
> this is filtered or not, I'm not clever enough to write there) can add
> examples or remarks.
>
> This part is incredibly usefull
> may be we sould do a similar thing?
>
> If I remember well, when discussing the wiki, the discussion was
> mostly about editing the original document. Here the goal is to add
> user experience to it
>
As someone who has spent some time on the PHP documentation team -
maintaining the user notes (weeding out incorrect or complete spam
notes) takes a massive amount of effort. Be prepared to invest a great
deal of time weeding out the useless notes to try and ensure that only
the useful notes remain, if you decide to go this route. I believe the
PostgreSQL folks have had a similar experience. The idea is great, in
an ideal world; in practice, it's very demanding.
Oh - and Sergiusz - the PHP docs and their user notes are mirrored all
over the world, and notes can be added from any one of those mirrors
to any given page and they will be reflected. Compare us.php.net vs.
ca.php.net vs. ca3.php.net -- all different mirrors, all with the same
notes. It can be done, if you really want to.
--
Dan Scott
Laurentian University
