Re: Documenting the Doc Team

[Shaun McCance <shaunm gnome org>]

On Wed, 2009-06-17 at 10:46 +0200, Milo Casagrande wrote:
>  * better explanation of the version/revision numbering. We have a
> "problem" now with Mallard: in the "past" there was usually one big
> file and "usually" modifying the document meant a bump of the version
> number. How can we handle it now? We will have small files, one per
> topic: how can we handle the reversion/version numbering scheme? Do we
> bump the number with a single modification of the file? We can end up
> with file of the same set with different version, will it be a
> problem?

So I sort of glossed over the revision element with you guys.  Here's
a more complete explanation.  You can have any number of revision
elements in an info element as you want.  This can be used to track
history or to record different types of revision information.  The
spec is deliberately loose about this.  We need to decide our best
practices.

Each revision element can have five attributes:

status - The status designation, as we currently use them
date - The date this revision was made, in the One True Date Format
version - The version number of this page or section
docversion - The version number of the document the page is in
pkgversion - The version number of the package the document is in

Pulse's current status tracking demands that version numbers match
the two-number stable version of the package.  This prevent us from
having stale status information.  For Mallard, when Pulse tries to
find revision information for the current release, it will prefer
pkgversion, then docversion, then version.

We also need to decide how we want to record the status of the
document as a whole.  We would record this in index.page.  Maybe
something like this:

<info>
  <!-- Status for index.page -->
  <revision version="..." docversion="2.28" status="..."/>
  <!-- Status for the document has no @version -->
  <revision docversion="2.28" status="..."/>
</info>

Or maybe we don't need separate revision elements.  Maybe we can
just consider the status of index.page to be the status of the
document.  Since index.page is a guide, it will have little real
content to review.  Will we need to track its status separately?
I don't know.

In any case, I expect that as we start to use status tracking
more, we'll find room for improvement.  We can always change,
so let's not worry too much about getting it perfect on the
first iteration.

--
Shaun