discuss: List of Docs needing review (was Re: the good the bad and the ugly)
Subject:
List of Docs needing review (was Re: the good the bad and the ugly)
From:
David Lawyer ####@####.####
Date:
25 Nov 2003 00:01:39 -0000
Message-Id: <20031124224916.GC533@lafn.org>
> On Sun, Nov 23, 2003 at 10:56:06AM -0800, David Lawyer wrote:
> > There is so much review work to do that it's important to take shortcuts
> > in reviewing, especially for new submissions.
>
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.
> 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.
> > 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]
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".
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
