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.

• 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 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

The status information is recorded in DocBook using the releaseinfo element. This should be placed in the bookinfo or articleinfo of the document. The revision attribute should be set to the dotted pair version of the stable release version of the package, such as "2.24". Do not use the micro version number. Do not use the unstable version, even if the package is still using them.

The status designation is recorded in the role attribute of the releaseinfo element.

Reviews and planning documents may be recorded as ulink elements inside the releaseinfo element. Each ulink child of releaseinfo will be displayed by Pulse. Set the url attribute to a publicly accessible URL, such as a mailing list archive page. The content of ulink may be empty; Pulse will retrieve the URL and display the title of the HTML document. Set the type attriute of the ulink element to one of the following:

bug

Link to a bug report that is considered critical to fix

planning

An outline or other planning document

peerreview

A peer review

techreview

A tech review

finalreview

A final review

review

Any other type of review

Pulse will pick up the status information and the reviews and display it on the page for the document. In order to ensure that we don't use incorrect information from another release, Pulse will only use data from releaseinfo if the revision attribute matches the release series of the current branch, as determined from the current version number set in configure.in or configure.ac.

Here is an example taken from the Empathy Manual:

<releaseinfo revision="2.26" role="incomplete">
  <ulink type="bug" url="http://bugzilla.gnome.org/show_bug.cgi?id=561033" />
  <ulink type="planning" url="http://live.gnome.org/Empathy/Documentation" />
</releaseinfo>