editors: Re: Keeping up-to-date (was Re: Document Lifetimes?)
Subject:
Re: Keeping up-to-date (was Re: Document Lifetimes?)
From:
Tabatha Marshall ####@####.####
Date:
12 Nov 2003 07:44:50 -0000
Message-Id: <1068623062.17424.39.camel@mysticchild>
On Tue, 2003-11-11 at 22:46, David Lawyer wrote:
> While it's nice to have such a system, this aspect of it will not solve
> our problems unless we have more reviewers. But the main problem is not
> that of not having enough reviewers, but that of either getting authors
> to do much more work, or finding a lot of new authors and maintainers
> that can put more skilled effort into it. Reviewers can point out
> problems but the best solution is to get authors to closely follow the
> field covered by their docs and to keep them up to date.
>
> I've mentioned before that many docs are very much out of date even
> though they are frequently updated. The reason is that the update may
> only correct a few things noticed by readers such as a broken url,
> typos, an unclear statement, etc. There may be better and newer ways to
> do the job that are not mentioned in the doc, but most readers don't
> know about them. If they did, they would probably be using such more
> modern methods and not be reading the doc.
What if there was an LDP Review Checklist? What if this checklist was
used as a way to have authors meet certain criteria in order to be added
to the collection?
I have come up with a basic checklist of things we look for in the
current review process (bearing in mind that we are not all able to
perform technical reviews):
1. License & Copyright
2. Metadata
3. Abstract clearly defines document scope
4. Spelling
5. Grammar
6. Technical accuracy
7. Clarity of text
8. Organization of material
9. Type of markup
This checklist, used in the review process, could become part of the
approval process, and also be included in the criteria for inclusion in
distro copies. Being included in a distribution should be a high
incentive for authors to keep their work up to date, and I don't
personally think it's too much to ask. With a little guidance from
reviewers and other members who are familiar with the ropes, this should
be a realistic expectation.
> But a database can help by presenting wish lists of needed HOWTOs, and
> by listing existing maintained docs where the author needs help
> maintaining or getting someone else to take over a doc entirely. Then
> we can say to the LUGs: This is what needs doing, could you volunteer to
> help? We need to have every author be also a recruiter. If they join
> a local LUG and attend meetings, mentioning the LDP there would help.
Agreed. The document status can be used for this purpose. The
information can be extracted and automatically written to a page for
other people to look at and see what needs doing. The list of documents
could be broken down to new, pending scheduled review, review in
process, etc., and these would be grouped as such for others to easily
see (maybe this includes a status for a document that needs a "quality"
check).
This could be how a reviewer finds a document to review, and how someone
who wants to do a technical review could find a suitable project.
--
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)
