discuss: Reviewing existing docs
Subject:
Reviewing existing docs
From:
David Lawyer ####@####.####
Date:
20 Nov 2004 10:14:27 -0000
Message-Id: <20041120101428.GC767@davespc>
There's a lot of work to do here but some kind of a database is needed
for reviewer notes, etc. Due to lack of reviewers, sampling is one way
to go. Another is "grep -i". One searches for the names of recent
developments and if they are not found it means that the doc hasn't be
kept fully up-to-date. I've looked over several docs and I've found
that in a many cases the doc has only been superficially updated. The
update date is recent but only a small percentage of the contents that
need updating have been updated.
This is likely to happen if a maintainer just makes changes based on
what readers report. Readers often don't know about recent
developments, etc. so they mainly report typos, broken links, lack of
clarity, etc. There are exceptions but based on my experience, just
responding to reader feedback will not keep a doc up-to-date.
This means of course, that we have a lot more out-of-date documents than
one would expect by just looking at the last revision dates. What to do
about this? First, find the docs that need revision by sampling
parts of them. This is fast but one needs to know the subject including
recent developments. Then, what should be done if the author isn't
adequately maintaining the doc. This unfortunate situation is likely
true for a majority of authors/maintainers. The obvious solution is to
either find a new maintainer that has the time to spend on fixing the
doc or get the current maintainer to fix it. Bringing a doc up-to-date
(and doing a good job of it) may take almost as much time as rewriting
the doc from scratch. We need to let people that want to take on
maintaining an out-of-date doc know that it will be a lot of work and
that they likely will need to do a full revision.
We could send out form letters to authors that haven't been adequately
maintaining their docs and find out what they want to do. Either put a
lot of time into updating it or look for a new author. It would save
LDP a lot of work if the current author looked for a new one by perhaps
contacting LUGs, people who post correct answers on mailing lists, etc.
We could suggest this but in most cases LDP will likely need to find new
authors. Perhaps when someone volunteers as an author, we should ask to
look at something s/he's written, or search for stuff by them on the
Internet.
Perhaps the word "maintainer" shouldn't be used since the maintainer
needs to also be an author and write about new developments and how to
utilize them while putting some old methods in an appendix, etc.
What we really need is a new leader that can spend full time trying to
solve these problems and recruit others to help also. And remember
Poet and Al Dev. We can't just let anyone who wants to volunteer do so.
I was prompted to write this since I'm trying to write a very short
reviewer HOWTO. For existing docs, there's the above problems plus the
problem of authors that can't be located or don't respond. I think that
the reviewer should also be a recruiter and try to find someone to
become a new author if this is needed. Furthermore, the reviewer needs
to track the doc to make sure that the new author actually does the job
adequately. For example, someone took over the System Administrator's
Guide about a year ago, but sampling indicates that it's still very much
out-of-date.
David Lawyer
