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.
Within OSS Watch, all proposals for new documents are lodged with the content editor for consideration. The proposals usually come from OSS Watch staff but occasionally may come from the wider community. The content editor evaluates a proposed document using the following criteria:
Once the content editor has determined that a proposed document should go forward to 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 write documents -it is one of the duties that we have in common- 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. On reaching its final draft the content editor ensures that the document conforms to house style and quality standards before publishing. Documents are composed in a variety of ways. Some internally authored documents are written in XML from the start, some documents begin life in the OSS Watch wiki and most commissioned work is composed in the author's choice of format and then converted to XML by the content editor at the same time as applying the house style.
More recently OSS Watch has been making use of its public wiki to create the frameworks for new documents. For example, if a consultation with a stakeholder reveals that a new document is needed, it will often be started in the wiki. In this way the stakeholder can help shape the document, and can receive the information that they require more quickly. If the document's author feels that the document is of sufficient quality, they can ask the content editor to assess the document as a candidate to become an official OSS Watch document. (In many cases the author will seek team comment before submitting to the content editor but this is not a mandatory step at this point in the process.) If the content editor feels that the document is good enough it will be marked up as XML and circulated 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.
An OSS Watch document may be live or archived:
OSS Watch documents are principally written in an XML notation called the Text Encoding Initiative (TEI). Using XML 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 TEI header. Other information relating to the review process is also recorded in the TEI header and is described below.
Each document is reviewed 6 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 month and where possible the reviewer is not the original author. The review information is recorded in the XML source of the document itself by adding a change record to the TEI header. This change record will record the date of the review, the person conducting the review, the type of review, and the outcome. Some of that data is used to add the Last reviewed date that appears at the bottom of the published document on the website.
Every document that is published has a set of milestones associated with it. The minimum set of milestones belonging to each document is:
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.
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.
The purpose of this review is to consider whether the document is relevant any longer 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 no longer be relevant. If this is the case the document would 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:
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. JISC, our funder, agrees. JISC funded the QA Focus project whose remit is to support the JISC's Information Environment programme by encouraging participating projects to develop appropriate quality assurance processes which will ensure that project deliverables comply with standards and best practices. JISC also helps to fund the Web Focus project which aims to maximise the effectiveness of the academic community's investment in web technologies. OSS Watch's life cycle policy dovetails with the advice and recommendations coming from both the QA and the Web Focus projects and so follows JISC's best practice.
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. 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.
It is licensed under the
Creative Commons Attribution-ShareAlike 2.0 England & Wales licence.
OSS Watch is funded by the Joint Information Systems Committee.