On Thursday, July 26, 2001, at 02:53 PM, Rasmus Lerdorf wrote:
> The notes in the online manual are piling up again.
My apologies, for a while I was cleaning at a much faster rate,
but then my consulting business became viable. :-) (A cleaner
can take out about a third of the notes, it just takes
docbook/XML skills and mousing abilities)
> The job of managing
> these things is much much too big for a small group of people. What do
> you guys think of the idea of making it possible for individuals to
> register themselves as maintainers of individual manual pages?
Well, it depends on usage and interest. Part of the note
maintenace is about deleting flames and questions, another part
is about about correcting documentaion, yet another part is
about maintaining and cleaning duplicate notes and typos in
notes. The first and third parts are easier, but not as many
people know know docbook/XML. In reference to individual
sections, to clean and upgrade your, you must have the basic
skills to clean and upgrade all (CVS, docbook..)
> That is, I might decide that I know just about everything there
> is to know
> about the strlen() function. So I sign up to maintain any
> notes submitted
> to that particular page. (Surprisingly there are quite a few
> notes on the
> strlen() page)
Well, there's no examples, no verbose description... basically,
it's an under-documented function. The problem here is not about
the first or third cases (note cleanup), but a function with a
total of 8 words of explanation. To really "remove" the notes
might be a disservice. One solution would be to increase the
documentation.
Something that would be *really* helpful is a report of the
number of notes for a given section, and then the section, page
by page. This could help in terms of focusing clean-up efforts,
as well as gain an idea of where documentation expertise is
needed... signing of for one page makes sense in one context,
but, for example, the pg_* functions... do I sign up for 20
pages, to maintain it? If I wanted to dive in, and document a
function with a lot of notes, how do I find it?
I guess I'm suggesting something like the bug-count mailing,
only focused on errata instead.
> And it should be possible for multiple people to sign up to
> maintain the
> notes for a particular page just to have some redundancy. What
> it would
> mean is that whenever a noe is submitted to that page the
> people signed up
> as maintainers would get an email and it would then be their job to
> evaluate the note and decide if it should be rolled into the
> documentation, left as a note or deleted.
Well, I already use some filtering to evaluate areas where I
have stong familiarity....
I see more feeback in this thread, so I'll stop now and move to those...
-Ronabop
--2D426F70|759328624|00101101010000100110111101110000
[EMAIL PROTECTED], 520-326-6109, http://www.opus1.com/ron/
The opinions expressed in this email are not necessarily those
of myself,
my employers, or any of the other little voices in my head.
