The life of an OSS Watch document

by Elena Blanco on 27 November 2006 , last updated 9 September 2013

Introduction

OSS Watch takes its written outputs seriously. So, it seems, do others: OSS Watch documents are referred to increasingly frequently by other projects and organizations in the academic community. A potential point of concern for OSS Watch is that when our documents or reports are used by others, they are used as a definitive source of information because they have come from us. Now, we are very pleased to be considered an authoritative source of information on matters relating to open source software; that is exactly what we set out to be. But this position does not come without responsibility. As a result, we strive very hard to ensure that our documents, be they briefing notes, conference reports, book reviews or opinion pieces, are both accurate and of a good quality.

To achieve this, it is necessary to subject all of our documents to periodic review. It is simply not enough to publish a document and then to forget about it. Every document produced by OSS Watch is subject to our document life cycle policy, a policy that governs the consistency, quality and integrity of our documents. To achieve this, the policy covers all of the key aspects related to each and every OSS Watch document, such as its inception, its status, and the review process itself.

Document inception

Within OSS Watch, all proposals for new documents are discussed by our team for consideration. The proposals usually come from OSS Watch staff, but occasionally may come from the wider community. The team evaluates a proposed document using the following criteria:

Is this document relevant to the people and projects supported by OSS Watch?
Will this document cover material already covered by a different document?
Does this document cover material in a subject area that is already over- or under-represented?
Does OSS Watch have the expertise and resources to write this document or will it need to be outsourced?

Once the team has determined that a proposed document should be written, it is allocated to an appropriate author. That author is usually a member of OSS Watch staff, but in some cases we commission an external author who may be an expert in the field. All OSS Watch staff are expected to contribute to documents and most team members will become the lead author on a document but the length of time that it takes to write a document varies according to both the subject and the author. Once drafted, a document will always be commented upon by the team as a whole, so each document is a collaborative work to some extent.

Team comment

When the document’s author feels that the document is ready, they will circulate it for team comment. Even if the team members have already previously commented on the document, this is the point at which all team members are expected to read and comment upon the document. After the team’s comments have been incorporated, the document is finally published on the OSS Watch website.

Document status

An OSS Watch document may be live or archived:

A live document is one that is actively subject to the review process. However, over time the document’s relevance is likely to diminish, until it is finally archived.
An archived document remains on the website in order to preserve any external links that may be pointing at it, but the document is clearly marked as archived and all links to it from current OSS Watch documents are removed. At this point, the archived document is no longer subject to the review process and will be left as is.

OSS Watch documents are principally written in Markdown with a YAML header. Using YAML allows meta data relating to that document to be recorded in the source of the document itself. Therefore we are able to record a document’s status alongside other information such as the author and publication date in the header. Other information relating to the review process is also recorded in the header and is described below.

The review process

Each document is reviewed six months after publication, for integrity, and again 12 months after publication, for integrity and relevance. Any document found lacking in either area at the 12-month review is either edited, rewritten as required or archived. OSS Watch staff conduct reviews of documents every quarter; where possible, the reviewer is not the original author.

All our content is managed using Subversion, and review information is recorded either in the commit comments, or as additional comments within the content’s YAML header.

On most OSS Watch documents on our website you can see the date of the last review in the sidebar.

Document milestones

Every document that is published has a set of milestones associated with it. The minimum set of milestones belonging to each document is:

Date of publication
Date (month) of integrity review = date of publication + 6 months
Date (month) of expiration review = date of publication + 12 months

The integrity and expiration reviews are planned for the relevant month after 6 and 12 months have elapsed from the date of publication. In this way, all documents due for review in a particular month are dealt with together in order to make the review process as efficient as possible.

After an expiration review, and depending on the review outcome, a document may receive another milestone, such as a second expiration review date.

Integrity (or six-month) review

The purpose of this review is to check the integrity of the information presented. For example, a document may refer to the current version of a software product, so at this review the current version number of that software may need to be amended. Any links contained in the document are also checked and amended if appropriate. Links to new OSS Watch documents are also added where necessary.

Expiration (or 12-month) review

The purpose of this review is to consider whether the document is still relevant and, where necessary and appropriate, to update the content. For example, a conference report that describes the events of a conference that took place more than 12 months previously may reflect issues that are still relevant but equally, it may no longer be relevant. If this is the case, the document will be archived, i.e. no longer linked to within the website but kept within the OSS Watch document repository and on the website. The outcome of an expiration review will be one of the following:

Document no longer relevant and is archived. In this instance, the document is retained within the document repository and on the website but is flagged as archived and links to this document from other OSS Watch documents and index pages are removed.
A rewrite of the document required to maintain relevance.
Document is both relevant and accurate and is retained on the website. No editing of the content is required

Unless a document is archived, it will be scheduled for another review in 6 months.

Is it worth it?

It is clear that following the type of document life cycle described here is a time-consuming process that requires considerable resources. So is it worth going to all this bother? OSS Watch firmly believes that it is. In order to be an authoritative source, the information supplied must have a high degree of integrity and must be of a uniform quality.

We believe that the only way to ensure the quality and integrity of our documents is to keep looking at them, refining and tweaking until the time comes to retire that document. From time to time we may implement our review cycle slightly differently, but we remain committed to the principle of regular review. The result of this is, we hope, a better OSS Watch.

We welcome comments on all of our material, so if you see something you like or even something you disagree with, then please do get in touch.

OSS Watch provides unbiased advice and guidance on the use, development, and licensing of free software, open source software, and open source hardware.