Tracking Documentation Status

This page details a proposal for how we could track the status of our documentation. This page is theory. This is not consistently applied in praxis!

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.

• The authors have not assigned a status to this document. Pulse will default to showing none if no status is recorded in the DocBook, or if the status in the DocBook does not come from this list. Editors should evaluate these documents and assign them an appropriate status.

• This document has little or no real content. It may have simply been created by the developers in order to have it included in the build.

• The document has the basic structure in place, but the authors have not yet written all the content. There may be some empty sections. Some content may be little more than notes from authors to themselves about what to write.

• The authors have written all the content, but they still intend to clean up the language or markup. Reviews from developers for technical correctness are useful at this point. Reviews of language usage or markup may not be useful. Note that the draft status may be skipped. Some authors prefer to get everything down first, then deal with organization, language, and markup. The draft status is for these people. If you try to write things polished from the beginning, you can skip directly to review.

• The document was once complete or nearly complete, but needs to be updated to reflect changes in the software. At the beginning of a new release cycle, authors should switch completed documents to this status. Authors should never move a document beyond this status before feature freeze, since there may still be software changes that will need to be addressed.

• The authors consider the document complete. Editors should review the document at this point. Details on reviewing documents can be found below.

• Editors and developers have reviewed the document, as described below. The authors have dealt with those reviews and consider the document to be finished.

• A senior member of the documentation team has reviewed the document and approved it.

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 documents, 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>