discuss: List of Docs needing review (was Re: the good the bad and the ugly)
Subject:
Re: List of Docs needing review (was Re: the good the bad and the ugly)
From:
doug jensen ####@####.####
Date:
25 Nov 2003 19:23:24 -0000
Message-Id: <20031125193617.GA5532@ispwest.com>
On Mon, Nov 24, 2003 at 02:49:16PM -0800, David Lawyer wrote:
> On Sun, Nov 23, 2003 at 06:30:54PM -0700, doug jensen wrote:
> > The page requesting a review from the user, would be for older documents
> > that are already available, so wouldn't apply to new submissions. It's
> > intended as a quick way to encourage feedback from people reading
> > documents that haven't been updated for a long time. It would also
> > serve as a clue to the user that the HOWTO may need changes. The
> > authors probably aren't responding to feedback,
>
> I think that in most cases the authors can be contacted. People who
> wrote docs are fairly computer literate and usually have an email
> address (perhaps not the same as in their doc). But when contacted, the
> author may say they just haven't found time to maintain it or haven't
> followed the topic of the doc as they've been working on other things.
>
> I think the main reason for lack of revision is not that they don't have
> time to write a few pages to update their doc, but that they haven't
> followed recent developments in the topic and would have to do a lot of
> research prior to writing an update.
>
> If a reader finds a doc that is quite out of date, they may not bother
> writing to the author. The reader reasons that the author must realize
> that it's out-of-date so why tell the author what the author already
> knows. Thus the author just doesn't get hardly any feedback.
How can the reader provide feedback if the author doesn't update their
email address?
>
> > because it is unlikely that the users haven't made some good
> > suggestions in several years. I believe that it would be useful to
> > get feedback from users of those HOWTOs, don't you?
>
> Most of LDP's docs several years old have been archived long ago.
> But a few may still be with us.
There are currently ninety-four HOWTOs that were last updated prior to
2000. Could you expand on your claim that most old docs have been
removed?
>
> > > Wouldn't an informative review be longish rather than short?
> >
> > Here's a review by David Horton that I would consider both very
> > informative and very short: Shadow-Password-HOWTO Updated: Apr 1996
> > Michael H. Jackson, From: "David Horton" ####@####.#### I
> > tried to use the info in the shadow-howto a while back. It's not
> > badly written, it's just very out of date. Here's why:
> >
> > * The version of the shadow suite mentioned in the howto is far
> > behind. * The links to download locations do not work. * The howto
> > talks about installing shadow on your distribution. Shadow is
> > standard on most distros, so this section is not needed. * The howto
> > also covers patching programs to work with shadow which is also not
> > needed since shadow is standard on most distros.
> >
> > The section on adding shadow support to your own programs may still be
> > useful or maybe not. I am not a programmer so I do not know.
>
> So it looks like it should be put into the unmaintained directory. Then
> someone needs to look it over and perhaps put it into an "obsolete"
> directory after extracting the part (if any) useful for programming.
> [snip]
I agree that HOWTO should probably be move away from the distribution of
current HOWTOs. But the point of including that review in the text of my
email was to show you that a review could be short and informative. After
all, you asked the question ;).
>
> So part of the problem is not having a database with HOWTOs, etc. in
> various categories such as "author wants out, looking for new author".
That would be good. Alternatively/also, the author could put a
statement in the HOWTO that a new maintainer is wanted. That way the
author could select a replacement.
>
> Regarding a list of docs needing review, I support this idea, but again
> having a database to support this would help a lot. Lampadas would
> perhaps, permit one to tag docs needed review and maintain an audit
> trail to show who tagged it, and when.
>
> David Lawyer
>
Can't things be done now while we are waiting for Lampadas?
--
Doug Jensen
