Document Life Cycle Best Practices

Version 2024.08.22

Abstract

This document contains both a summary of the work product process (relevant to TC Process version 22 July 2020) and some guidance on how to streamline that process. It also discusses how an OASIS Technical Committee (TC)’s Work Product progresses through the various development stages of its lifecycle.

In addition to defining some best practices, this document also defines three optional standing rules that a TC may choose to enact to simplify the process of moving documents through the various development stages. These standing rules simplify when ballots are needed, clarify when and how approvals are done, can reduce voting fatigue, and can reduce delays due to administrative processes. These standing rules can be adopted on a document-by-document basis or be adopted globally by the TC for all documents. In the latter case, a TC may consider doing this during the formation of the TC.

Scope

The best practices and standing rules included in this document can be applied to all Standards Track and Non-Standards Track Work Products of a Technical Committee. These can be
adopted by any OASIS Technical Committee on a document-by-document basis or for all documents produced by that TC.

Notices

1. Introduction
2. Concepts and Background
3. Document Stages
4. Summary and Conclusions
Appendix A – Work Product Process State Diagram
Appendix B – WD and CSD Numbering Examples
- B.1 Numbering Without Standing Rule 1
- B.2 Numbering With Standing Rule 1

1. Introduction

1.1 Motivation

Currently, most Technical Committees process documents through their lifecycle in a way that causes unnecessary delays, ballots, and administrative process. This document tries to address these issues.

1.2 Abbreviations and Acronyms

This document uses the following abbreviations and acronyms:

CN – Committee Note
CS – Committee Specification
CND – Committee Note Draft
CSD – Committee Specification Draft
FMV – Full Majority Vote
NWI – New Work Item
OBCP – OASIS Best Current Practices
SMV – Special Majority Vote
TC – Technical Committee
TR – Technical Report
TRD – Technical Report Draft
WD – Working Draft
WP – Work Product

1.3 Definitions

New Work Item – A contribution that represents a proposed new TC Work Item.

Work Item – A document that is either at the Working Draft stage or at a Work Product stage.

Working Draft – A document that has not been approved as an official Work Product of the TC.

Work Product – A document that has been officially approved by the TC as a Standards Track
or Non-Standards Track document.

2. Concepts and Background

2.1 Contributions

A contribution is a verbal or written comment, suggestion, or document that is submitted to a TC and contains either a proposed New Work Item or proposed edits, changes, additions, or suggestions to an existing Work Item (regardless of the existing Work Item’s current stage). This OBCP document focuses on contributions that create New Work Items. While TCs need to review and consider all contributions, they do not need to accept or adopt (in part or in full) the contribution.

2.2 Document Stages

All Work Items start as a contribution to a TC, and starter templates for these contributions can be requested from OASIS Admin. Once a contribution is approved by the TC, it becomes an official Standards Track Work Product or Non-Standards Track Work Product and will progress through the following stages. A contribution may go through several revisions at the Working Draft stage before it is approved as an official Work Product.

1. Working Draft
2. Standards Track Work Product stages
- a. Committee Specification Draft
- b. Committee Specification
- c. OASIS Standard
3. Non-Standards Track Work Product stages
- a. For Committee Notes
  - i. Committee Note Draft
  - ii. Committee Note
- For Technical Reports
  - i. Technical Report Draft
  - ii. Technical Report

2.3 Documents Do Not Revert To The Working Draft Stage

Once a document has been approved by the TC and advances to a Work Product, new versions of that document do not start over at the Working Draft stage. The Working Draft stage is for contributions that have not yet been approved as official Work Products. For example, when a contribution has been approved as a Committee Specification Draft, new versions of that document do not start over as Working Drafts.

3. Document Stages

3.1 Working Drafts

The OASIS TC Process does not talk about contributions or Working Drafts, as such, this section gives some guidance on what they are and how they should be understood.

A contribution may go through many revisions before it is either approved or discarded by the TC. Each revision of a contribution, including the first submission, is considered a Working Draft. Once a Working Draft is approved by the TC it becomes either a CSD, CND, CN, TRD, or TR.

Said another way, a Working Draft is a Work Item that has not yet reached a sufficient level of maturity as determined by the TC to be considered for and approved as an official Standards Track Work Product (i.e., CSD) or Non-Standards Track Work Product (i.e., CND, CN, TRD, or TR).

3.1.1 New Versions

TCs do not approve new versions of a Working Draft. Working Draft documents are developed either by the original contributor or the editors of the document and can be revised, updated, and released as often as the original contributor or editors desire. Each version of these documents can and should be uploaded to the official TC document repository in the “Working Drafts” directory.

3.1.2 Numbering

The first release and initial contribution to the TC should have a document stage version of “Working Draft 01”. For each additional version of the document, the stage version value should be incremented (e.g., 02, 03, 04, etc). Please see the OASIS Naming Directives document for more information.

3.2 Specification/Note/Technical Report Draft Documents

Once a Working Draft has been deemed sufficiently mature by the TC, the TC can approve the current version of the Working Draft as a Standards Track or Non-Standards Track Work Product (i.e., CSD, CND, CN, TRD, or TR) through a Full Majority Vote. Please see the TC Process for more information on how to perform ballots. NOTE: it is possible for documents to go directly from a WD to either a CN or TR due to them not needing a public review.

The figure below shows a document that was approved as a Work Product after several revisions as a Working Draft.

3.2.1 Updates

CSD and CND documents are developed by the TC and updates and revisions are performed by the editor(s) of the document. These documents can be revised, updated, and released as often as the TC desires.

TRD documents are developed by the author(s) with feedback from the TC and updates and revisions are performed by the author(s) and/or editor(s) of the document. These documents can be revised, updated, and released as often as the author(s) desire.

3.2.2 Numbering

The first version of a CSD, CND, and TRD needs to have a document stage version of “Committee Specification Draft 01”, “Committee Note Draft 01”, or “Technical Report Draft 01”. For each additional version of the document, the stage version value should be incremented (e.g., 02, 03, 04, etc.). Please see the OASIS Naming Directives document for more information.

3.2.3 Approvals

NOTE: the old Working Draft stage numbers are not retained once a document moves to the CSD, CND, CN, TRD, or TR stage, and new versions of a CSD, CND, and TRD do not start as Working Drafts.

The TC needs to approve each new version of a Committee Specification Draft and Committee Note Draft through a Full Majority Vote. The TC does not approve each new version of a Technical Report Draft, as Technical Report Drafts are developed by the author(s) with feedback from the TC. Please see the TC Process for more information on how to perform ballots. In regards to voting Section “1.11 TC Voting” of the TC Process says:

TCs may conduct electronic ballots. An electronic ballot may be conducted during a meeting using any tool available to the TC, including email, and the results must be recorded in the minutes. Electronic ballots outside of a meeting shall be made either by using the TC’s general mail list or the publicly archived electronic voting functionality provided by OASIS and must remain open for a minimum of 7 days.

This means that the TC may vote using the:

TC’s ballot tool
Issuing a call for objection to unanimous consent in a quorate meeting
Performing a live ballot (e.g. show of hands) in a quorate meeting
Issuing a call for objections to unanimous consent via email
Performing a ballot (email responses) via email

All non live votes require the ballot to be open for at least 7 days.

The motion, the second to the motion, and the results for each ballot must be documented per
TC Process. If a call for unanimous consent receives one or more objections, then a traditional
ballot must be used.

3.2.4 Standing Rule 1: Approving Additional CSD/CND Documents

As a standing rule, the TC may authorize the editor(s) to publish additional versions of a CSD or CND either on a regular basis or at their discretion without additional motions, calls for consent, or ballots. A Full Majority Vote is required to enact this standing rule.

NOTE: Before a Working Draft can become a CSD, CND, or a CN it must pass an actual Full Majority Vote, even if this standing rule is enacted. The same is true for a TRD, though the TC does not approve each new version of the TRD, the TC must approve it as a Work Product.

If a TC is going to enact this standing rule, the TC should do this as part of the first CSD or CND ballot, but this can be done at any time. This standing rule can be revoked at any time by the TC through a Full Majority Vote. Some TCs may enact this standing rule for all documents when the TC is formed.

With this standing rule in place and once a new CSD or CND version (after the initial CSD/CND passed a Full Majority Vote) is ready to be published, the editor(s) can ask the OASIS Admin to publish the document and publicly announce it without any additional motions, ballots, or votes.

For example, if this standing rule is enacted in a TC, then:

New CSD and CND documents should be uploaded to the official TC document
repository in the “Approved Work Products” directory by the editors, as these documents
are approved CSDs and CNDs, and they should have the suffix name of “-csd##” or
“-cnd##”. The “##” in this case is the CSD or CND number.

If the standing rule is not enacted:

New not yet approved CSD and CND documents should be uploaded to the official TC document repository in the “Working Drafts” directory by the editor(s) or chair(s) and should have a suffix name of “-pre-csd##-yyyy-mm-dd” or “-pre-cnd##-yyyy-mm-dd”. The “##” in this case is what the CSD or CND number will be once approved. For example, if CSD01 has been approved and the TC wants to approve CSD02, the document would have a suffix of “-pre-csd02-yyyy-mm-dd”.
Once the CSD or CND is approved (by a Full Majority Vote), it can be uploaded to the TC document repository in the “Approved Work Products” directory with the normal “-csd##” or “-cnd##” suffix.

3.3 Informal Document Feedback

TCs can receive feedback at any time about any Work Item they are working on. However, it is critical that all feedback from non-TC members be submitted through the public comment methods defined in the TC Process.

3.4 Public Reviews

See section “2.6 Public Review of a Committee Specification Draft” of the TC Process for more information about public reviews.

In summary, before a Committee Specification Draft can progress to a full Committee Specification, it needs to have at least one public review. The TC needs to approve starting each new public review via a Full Majority Vote. Please see the TC Process for how to perform Public Review ballots. The TC can request additional public reviews at any time through a Full Majority Vote. If a TC decides to do a public review of a CND or TRD, it may, but it must follow the same process as defined for a CSD.

3.4.1 Standing Rule 2: Approving Additional Public Reviews

As a standing rule, a TC may approve the chair(s) to open new public reviews with each CSD, CND, TRD release, on a regular basis, or at their discretion, without additional motions, calls for consent, or ballots. A Full Majority Vote is required to enact this standing rule.

NOTE: Before a CSD, CND, or TRD can go out for its first public review it must pass an actual Full Majority Vote, even if this standing rule is enacted.

If a TC is going to enact this standing rule, the TC should do this as part of the first public review, but it can be done at any time. This standing rule can be revoked at any time by the TC through a Full Majority Vote. Some TCs may enact this standing rule for all documents when the TC is formed.

3.5 Specification/Note/Report Documents

Approval of a Committee Specification requires a Special Majority Vote. The Special Majority Vote is set up and run by OASIS Admin. See section “2.7 Approval of a Committee Specification” of the TC Process for more information about approving a CS.

In summary, in addition to the requirements around public reviews, once the TC has decided that the CSD is complete and the text is sufficiently stable, the Chair(s) can request the OASIS Admin to open the Special Majority Vote. Please see the TC Process for how to perform a CS ballot.

Approval of a Committee Note and a Technical Report only requires a Full Majority Vote.

3.5.1 Numbering

The first version of a CS or CN needs to have a document stage version of “Committee Specification 01” or “Committee Note 01”. For each additional version of the document, the version value should be incremented (e.g., 02, 03, 04, etc.). Please see the OASIS Naming Directives document for more information. It is important to note that a Technical Report, once published, is not able to be versioned at the TR stage like a CS or CN.

3.5.2 Updates

TCs should avoid advancing a Committee Specification Draft or a Committee Note Draft to the next stage if immediate updates and/or changes are still needed and/or expected. Meaning, additional versions of a Committee Specification or Committee Note should be rare as these documents are considered a final deliverable.

In rare cases when the TC needs to update a Committee Specification or a Committee Note new versions of that document do not start over as Working Drafts. A TC may decide that the proposed changes warrant going back to the Committee Specification Draft or Committee Note Draft stage. This is especially true if the changes are material or they include significant breaking changes or the changes would represent a major or perhaps even a significant minor revision to the document according to semantic versioning. However, to be clear it is not required that a document go back to a previous stage.

Regardless of whether the document reverts back to the CSD stage or stays at the CS stage, each new version of a CS requires a new public review and the TC to perform a new CS ballot. Where each new version of a CN only requires a new CN ballot.

It is important to note that an update to an OASIS Standard does require starting over at the
Committee Specification Draft phase as it is considered an entirely new version.

When updating a CS or CN:

New not yet approved CS or CN documents should be uploaded to the official TC
document repository in the “Working Drafts” directory and should have a suffix name of
“-pre-cs##-yyyy-mm-dd” or “-pre-cn##-yyyy-mm-dd”.
Once this CS or CN is approved, it can be uploaded to the TC document repository in
the “Approved Work Products” directory with the normal “-cs##” or “-cn##” suffix and
then be published.

The Figure below shows an example of a Committee Specification Draft being approved as a CS (note: it does not show the approvals for public reviews).

3.6 Changes During Publication

Technical Committees (TCs) at OASIS strive to produce and publish high-quality documents and specifications. However, sometimes, during the publication process, the time after a successful ballot and before the document is published, non-material, minor, and editorial issues may be found that the TC wants to fix. These issues and problems can be resolved by the TC without doing another version and possible public review as stated in Section “2.2.4 Allowed changes” of the TC Process:

After a Work Product has been approved as a Standards Track or Non-Standards Track Work Product (for example, as a Committee Specification Draft), only non-material changes may be made during the publication process. These changes can only be made in coordination with the TC Admin and a summary of changes shall be sent to the TC mailing list. The TC may continue to make changes to the next Committee Specification Draft.

3.6.1 Standing Rule 3: Approving Editorial Changes

As a standing rule, a TC may approve the chair(s) and editor(s) and author(s) in the case of a Technical Report in coordination with OASIS Admin to also make editorial changes during the publication process without requiring approval from the TC. Editorial changes are things like formatting problems, updating the table of contents, fixing spelling errors, fixing typos, addressing grammar problems, updating links and references, etc. This does not include minor text changes or larger non-material changes, only editorial changes. It is important to note that the chair(s), the editor(s), the author(s) and the OASIS Admin must all agree that these changes are purely editorial. A Full Majority Vote is required to enact this standing rule.

If a TC is going to enact this standing rule, the TC should do this as part of the first CSD/CND/TRD or CS/CN/TR ballot for a given document, but it can be done at any time. This standing rule can be revoked at any time by the TC through a Full Majority Vote. Some TCs may enact this standing rule for all documents when the TC is formed.

4. Summary and Conclusions

This document outlines how TCs can advance a contribution through its entire lifecycle. It also clarifies that many of the ballots that are done today can be addressed through a call for unanimous consent or by enacting standing rules to pre-grant the chair(s), editor(s), or author(s) authority to release CSDs, CNDs, and TRDs and perform their public reviews either on a regular basis or at their discretion without additional motions, calls for consent, or ballots. It also clarifies how document versions are updated and shows how documents do not need to restart at the Working Draft stage. Meaning, once a document has advanced to the next stage, it does not need to go backward and start over at the Working Draft stage.

In some TCs today, a document may go through as many as 10 or more ballots before it is finally published as a final deliverable (e.g., CS 01). With these best practices and standing rules, documents could have as few as 2 ballots before they are published. For example:

The first ballot could be used to:

The first ballot could be used to:
- approve a Working Draft as CSD01
- approve the first public review, and
- approve all three standing rules that are covered in this document.
The second ballot would then be used to:
- approve the CS

This could greatly decrease voting fatigue and reduce the amount of time needed to support the
balloting process and, thus, ultimately speed up the delivery of published documents.

Development Status	Working Drafts Directory	Approved Work Products Directory
Working Draft Development	cacao-playbooks-v2.0-wd01, cacao-playbooks-v2.0-wd02, …
First CSD		cacao-playbooks-v2.0-csd01
Second CSD Development	cacao-playbooks-v2.0-pre-cs d02-yyyy-mm-dd, …
Second CSD		cacao-playbooks-v2.0-csd02

B.2 Numbering With Standing Rule 1

Development Status	Working Drafts Directory	Approved Work Products Directory
Working Draft Development	cacao-playbooks-v2.0-wd01, cacao-playbooks-v2.0-wd02, …
CSD Development		cacao-playbooks-v2.0-csd01, cacao-playbooks-v2.0-csd02, …

The Document Life Cycle for TCs – Approved 2024-08-22 Download