Tracking Documentation Status

This page details a proposal for how to track the status of our documentation. All documents will be assigned a status indicating its readiness for release. By recording the status and relevant planning and review links in the DocBook, we'll be able to track our documentation status using Pulse. This will make it easier for writers and reviewers to prioritize their work, and for potential new contributors to find something suitable to work on.

Status Designations

It is the author's responsibility to assign status designations to documents. How to do this is detailed in the Recording Status Information section below. Following is a list of status designations and their meanings.

doccycle.png

none

stub

incomplete

draft

outdated

review

candidate

final

Reviews

We strongly encourage people to have their documents reviewed by others. We classify reviews as either technical reviews or peer reviews.

Technical reviews should be done by developers of the documented software to ensure technical accuracy only. For most documents, one technical review is sufficient. Some larger documets, however, describe multiple pieces of software. These documents should receive technical reviews from developers of all relevant software.

Peer reviews should be done by fellow writers and editors. Peer reviews should check general content organization, language usage and spelling, and markup. Large changes to the content organization are probably unfeasible by the time the review phase has started, but they can be considered for the next release cycle. Not all peer reviewers need to check all aspects. For example, a good writer who is unfamiliar with DocBook may check everything but the markup. This is still a valuable review, and others can review the markup. Authors should try to get at least three peer reviews.

After an author feels she's gotten enough reviews and that her document is finished, she should mark the document as candidate. Candidate documents should be be reviewed by the documentation team leader or a senior team member appointed by the team leader. After the final review, the document can be marked final. Final documents are considered frozen, and no changes may be made to them without the approval of the documentation team leader and the translation team.

Recording Status Information

Use <revision> tags to record the page status. We currently use one <revision> tag per release cycle.

The pkgversion should specify which version of the software you are testing, this can be found in the About dialog.

The date should be the date that you last edited the page.

  <info>
    <!-- There were no changes between 3.2 and 3.7.92, so those revision tags are not listed -->
    <revision pkgversion="3.2" date="2011-08-21" status="draft"/>
    <!-- For the 3.8 release cycle, the last tested version of the application was the unstable 3.7.92, so that was the last update to this release tag -->
    <revision pkgversion="3.7.92" date="2013-03-20" status="review"/>
    <revision pkgversion="3.12" date="2014-03-16" status="candidate"/>
  </info>

Examples

If the latest version of the page has just been reviewed, then the <revision> tag for the 3.12 package needs to be updated:

  <info>
    <revision pkgversion="3.2" date="2011-08-21" status="draft"/>
    <revision pkgversion="3.7.92" date="2013-03-20" status="review"/>
    <revision pkgversion="3.12" date="2014-03-18" status="final"/>
  </info>

The application has had changes for the 3.14 release cycle and the page is now outdated. A new tag can be added to show this:

  <info>
    <revision pkgversion="3.2" date="2011-08-21" status="draft"/>
    <revision pkgversion="3.7.92" date="2013-03-20" status="review"/>
    <revision pkgversion="3.12" date="2014-03-18" status="final"/>
    <revision pkgversion="3.13.1" date="2014-04-20" status="outdated"/>
  </info>

DocumentationProject/StatusTracking (last edited 2014-03-18 13:01:27 by EkaterinaGerasimova)