Re: Documentation Status Tracking

[Shaun McCance <shaunm gnome org>]

On Sat, 2008-09-27 at 08:00 -0300, Leonardo F. Fontenelle wrote:
> Pulse and looks very interesting, and I hope it will help the
> Documentation Project enhance the overall GNOME documentation in
> quantity and quality. I'm not a documentation writer, but I'd like to
> ask/suggest three points about the Status Tracking:
> 
> 1. What about an adjective instead of "update"? I didn't like "old" or
> "obsolete", but maybe you can find a more suitable word.

I agree with this.  I threw in "update" last minute.  Prior
to adding it, I was using "incomplete" for this purpose as
well, since the document is (or may be) incomplete compared
to the current software.  I thought it was worthwhile to be
able to distinguish between "never completed" and "needs to
be updated".  Suggestions welcome.

> 2. I agree all documentation must be reviewed, but I also agree the
> process seems too heavy, i. e. maybe we can't get all those reviews.

I don't expect us to hit 100% completeness any time soon.
It will take time to build our team and our experience to
be able to attain this.  But I don't want to mark things
as complete just because we don't have time to make them
any better.  I want us to see where we need to improve.

> 3. What's the relation between Pulse and Mallard? If I got it right,
> Pulse is going to be used right now, and when Mallard starts being used,
> Pulse will be tweaked to read information from Mallard's XML documents,
> instead of DocBooks. Is that so?

Correct.  Pulse and Mallard are largely orthogonal.  Pulse
can track lots and lots of stuff.  Once we start actually
using Mallard for our documents, it will take only a small
amount of work to make Pulse track those documents as well.

Also note that we probably won't completely drop DocBook
any time soon.  There are quite a few documents for which
DocBook is simply better suited.  In time, we may be able
to develop mechanisms within Mallard to make it suitable
for those documents.  But initially, many documents will
stay in DocBook.

--
Shaun