editors: Thread: Re: Keeping up-to-date (was Re: Document Lifetimes?)

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)

On Wed, 2003-11-12 at 09:38, Emma Jane Hogbin wrote:
> On Tue, Nov 11, 2003 at 11:44:23PM -0800, Tabatha Marshall wrote:
> > 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?
> 
> Yes please. I will add this list to the LAG (I promise I will finish the
> revisions soon!). It should also go into the Linux Documentation Project
> Reviewer HOWTO by David Merrill and Joy Yokley (last revised in 2001...).

This what I have so far:

1.  Presence of License & Copyright
2.  Presence of Metadata
        -title
        -author name
        -author email
        -organization (if any)
        -contributors (if any)
        -pub date (month and year)
        -revhistory
                -rev version
                -date of revision
                -author initials
                -revision remarks
        -abstract
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

Before we revise the HOWTOs, could everyone tell me if anything seems to
be missing?

Thanks!

Tab

-- 
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)

On Wed, Nov 26, 2003 at 07:53:28PM -0800, David Lawyer wrote:
> Suppose it meets all the above criteria but suggests very inefficient
> methods of doing the job.  Or suppose it ignores useful software tools.
> Or tries to sell the reader software developed by the author (as Al Dev
> did).  I not sure you can put everything in a list, there are just too
> many ways an author can blunder.

The point of the excercise is to try and highlight as many problem areas
as possible. If there are other areas you think need to be included in
the checklist, then suggest them. Your email above almost suggests there's
no point in having a checklist at all. I don't think that's what you meant
though.

emma

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]