discuss: Some of the main problems of the libre documentation
Subject:
Re: Some of the main problems of the libre documentation
From:
Tabatha Marshall ####@####.####
Date:
19 Jun 2003 21:03:30 -0000
Message-Id: <1056056707.6721.46.camel@mysticchild>
On Wed, 2003-06-18 at 21:41, David Lawyer wrote:
> It's equally important to review existing documentation. One job is to
> establish rough review priorities for some of the existing
> documentation. First should come all docs by Al Dev. But then after
> that is underway?? One might look for docs on the same topic that need
> merging. It's also desirable to split up the work and have many docs on
> various aspects of the same topic when there is a feasible way to
> establish boundary lines between documents. An example might be a
> Printer-HOWTO and various mini-HOWTOs each on a different
> brand/model/series of printer.
I agree, David. Before I moved to review coordination I was trying to
do just that.
> Also, one might look at the docs that haven't been updated in a long
> time. Another check would be to find docs that have relatively short
> diffs for updates done infrequently. This implies that they haven't
> been changed much are are suspect for being out-of-date. This
> frequently happens. The maintainer only corrects typos, etc. reported by
> readers but fails to otherwise update the doc.
I would suggest that any documents more than a year old should be
reviewed first out of the existing material. The majority of the
collection (HOWTOs and mini-HOWTOs) require technical reviews. For many
authors, English is a second language, so there are still some existing
documents that could use language reviews.
Grouping documents and the other suggestions you mentioned above in the
first paragraph also make sense, if there are volunteers willing to work
on a specific subject and organize it like that. It might make things
easier than simply random reviewing of the existing collection. Once
the bigger ticket items are more organized, a review of the balance of
the documents will probably be a less intense job.
The collection should probably also be evaluated for any documents that
are so far out of date they need to be pulled and re-worked, since I
know this to be the case for some.
There's a lot of review work available, and a variety of ways to
accomplish the many tasks.
--
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)
