Subject:
Re: Dealing with poor maintenance by maintainers
From:
David Merrill ####@####.####
Date:
13 May 2002 16:21:53 -0000
Message-Id: <20020513171312.GC3264@lupercalia.net>
On Sun, May 12, 2002 at 04:26:29PM -0700, David Lawyer wrote:
> > * David Lawyer; ####@####.#### on 12 May, 2002 wrote:
> > >One is fixing any real bugs people report (with bugs including lack of
> > >clarity). If a bug is important, it needs to be fixed fast. Other bugs
> > >can wait a while, sometimes a few months if it's just a typo where
> > >people can easily figure out what you really meant to say. Maintainer
> > >refusing to help people with problems is OK, unless the problem is that
> > >the HOWTO doesn't cover something it should.
> >
> On Sun, May 12, 2002 at 08:37:00PM +0300, Togan Muftuoglu wrote:
> > a) How do you make sure the maintainer will fix the bug(s).
>
> If a maintainer habibitually neglects to fix bugs, then the maintainer
> should put his/her HOWTO on my proposed "New-Maintainer-Wanted" list.
> (Notice that I keep changing the name of this list; there are lots of
> alternate names.) If necessary, people in LDP would suggest this to the
> maintainer. I think that the vast majority of maintainers are
> reasonable people, and if they realize that they don't have time to
> maintain their doc, they will let someone else do it. If they will not,
> we should discuss what to do about it on the discuss list with possible
> action taken on it on the staff list. If these discussions have a cc to
> the maintainer (and we know the maintainer is reading email) then I
> think that some solution can be reached.
When I was Editor, I often sent letters to authors that said,
basically, as politely as possible, update your doc, maintain it, or
pass it on. MUCH more politely, of course, but that's the meat of the
message. "You doc has not been updated. Do you plan to update? If not,
we need to find a new maintainer" or the like.
/me ducks quickly, having pissed off all the authors.
If you got such a message, know that there are also other reasons I sent
it out. Your doc is not necessarily shite.
If a maintainer doesn't fix a bug, then we will. We cannot do
otherwise. If I ever felt a maintainer was just bad and not coachable
or teachable (will not work with the Editor!), then I would want that
author off the document, simple as that. Or the doc off the LDP and a
new one written.
If we do not set standards and expect docs to meet them, we wind up
with, well, what we have now in some cases. Do I sound fascist? I hope
not. I give authors every possible freedom and latitude. But we all
know there are some who write bad docs! It is an incontestible fact!
> > b) What is the acceptable time frame to fix the bug(s)?
>
> It depends on the severity and significance of the bug. We could just
> have some flexible guidelines like a week for a really bad bug to a few
> months for innocuous typos.
When we hear of serious and easily fixable bugs, we've been known to
just patch it and send the author the fix. Like when we had URLs that
all of a sudden were going to pr0n sites.
> c) What will happen if the maintainer has not fixed the bug(s) in
> relation to item "b"
>
> Same as for item a.
I say pull them off the document. We should abhor it. We should avoid
it. We should seek every other avenue first. Talk with the author.
Coach them. Try to build up their skills. But if all efforts fail and
the option is the status quo (suckage) or hurting the author's
feelings, then I can live with hurting the author's feelings. That
author is not helping the LDP, after all, are they? They are adding
bugs to it. We cannot allow that.
> > >The second aspect is keeping up with developments in the topic and
> > >adding the latest info on the subject to the doc. It's hard to tell if
> > >this is being done. Only the maintainer knows. And not always, since
> > >if the maintainer doesn't know about new developments, s/he may not even
> > >realize that changes are need. Doing this right takes a lot of time
> > >since procedures for old versions and old hardware still need to be kept
> > >in the doc, but put in an appendix, etc. and removed from the mainstream
> > >of the doc.
> >
> > replace the word bug(s) with development and the above question do apply
> But I don't say bug(s) in the above paragraph. So I'm not sure what you
> mean.
> >
> > >So what do we do about this? For one, we can establish a different
> > >organization of docs that need work, rather than just "unmaintained". I
> > >tentatively suggest:
> > >
> > >1. Unmaintained
> > >2. New-Maintainer-Needed
> > >3. Co-Maintainer-Needed
> > >4. Obsolete
Good idea, but I would implement it slightly differently. A doc is
either maintained or unmaintained, that is a binary switch. Leave it
alone. Also, unmaintained means it has no current maintainer. It could
be our best document, but still go unmaintained if the author abandons
it. That is not an indicator of quality and should not be pushed into
that role.
Instead, add the capability to mark it with "Maintainer Wanted", which
means that although it might be maintained, we still need a maintainer.
Note that this is also not an indicator of quality.
The "rating" is the indicator of quality. Once Lampadas goes live, we
will get many people rating documents, so it will be valuable data.
Right now, only we can give ratings, and we are too few to all go
through all the docs to rate them.
Obsolete=Archived in LDPD/Lampadas lingo. If it's obsolete, it is not
an active doc.
> > What happens when you create these categories ? Will distributions who
> > have dropped the package or at the process of elimination reconsider
> > their actions ? I doubt. RH and other key players are in business now and
> > they do not want to include document that are in conflict with their
> > system and documentation.
>
> Maybe we will get nowhere with RH, but we can always try. Improvement
> made at LDP will help insure that other distributions don't do the same
> thing.
We *will* get back into RH. I do not doubt that. Good ole Mr. Curley
will lead that effort and knowing him I have no doubt he will succeed
with our help. If we act on the information he brings back to us. And
we must, so we will.
> > Howto's are voluntary so you cannot force someone to fix the bugs or
> > update the document to match up with new versions of software or
> > development etc.
>
> Well, you can ask them to search for a new maintainer or co-maintainer.
Or we can look for a new maintainer ourselves. Either way, if the
current maintainer isn't cutting it, we need a new one.
> > I would say the licence should be changed so that if an HOWTO is
> > accepted "tldp" has the right to proofread and fix the bugs either
> > discovered during proofreading phase or whenever appropriate.
>
> It's best to have only the maintainer doing this. As for the license, I
> think we should come up with a licesense with options. One option
> would be that the doc can't be modified unless it is not adequately
> maintained. Then someone else could take over a doc which isn't being
> maintained. The other option(s) would allow modification without the
> consent of the copyright owner.
Our licenses by and large already allow this. The issue is one of
policy and procedure. We want to not become hard headed or, not to put
too fine a point on it, a@@es. No jackboots here, thank you. But at
the same time we have to identify poor documents and take whatever
steps are necessary to rectify them. Making sure we do everything we
can to resolve it in an amicable way with the maintainer if we can.
--
David C. Merrill http://www.lupercalia.net
Linux Documentation Project ####@####.####
Lead Developer http://www.tldp.org
O Seas of Caladan,
O people of Duke Leto --
Citadel of Leto Fallen
Fallen forever...
-- from "Songs of Muad'Dib" by the Princess Irulan
