Re: Manual notes maintainer assignment

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 ron@opus1.com, 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.