A Documentation Strategy for TDWG
Roger Hyam
Abstract
Documentation is the recording of information to define and support standards in a permanent format.
Study of the Internet Engineering Task Force (IETF), the World Wide Web Consortium (W3C), the Institute of Electrical and Electronics Engineers (IEEE), the Open Geospatial Consortium (OGC) and the Object Management Group (OMG) indicates the following is best practice in relation to documentation:
1. The organisation uses documents as primary outputs.
2. The organisation has clearly specified its documentation process.
3. The specification of documentation is included within the standards process itself to allow for controlled evolution.
4. Clear documentation templates and style guidelines are provided.
5. Clear IP and copyright policies are used.
It would be to the benefit of TDWG to have a documentation strategy that supports best practise. Such a strategy has been developed. It is based on three kinds of document.
Type 1 Documents are the normative parts of a standard. Examples of Type 1 documents are XML Schemas, human readable specifications that must be followed for compliance and controlled vocabularies. Type 1 documents are controlled by the TDWG standards process and are highly stable once ratified.
Type 2 Documents are parts of the standard that are non-normative (informative). Examples of Type 2 documents include examples, code and illustrations that accompany and clarify the standard. As parts of a standard they are also controlled by the TDWG standards process and are highly stable but not normative. The normative documents have precedence over them.
Type 3 Documents are those that fall outside the standard. Examples of Type 3 documents are tutorials, guides, primers, Wikis and discussion forums.
A “TDWG Standards Documentation Specification” has been developed and is proposed as a new TDWG standard to govern TDWG standards (Type 1 and Type 2 documents) going forward. It stipulates that standards take the form of a logical folder or directory that may contain any number of files and may be distributed as a zip or tar archive file. Human readable parts of standards should follow a specified layout and best practice style guidelines. They should be in XHTML format. Normative documents must be in English.
At a minimum, each standard must contain:
• The normative (prescriptive) form of the standard itself (e.g., XML Schema or human readable text);
• A 'Cover Page' document that summarizes the content of the standard but should also contain information on the 'Motivation' for the existence of the standard and the 'Rationale' for why the standard takes the form it does.
Documents should contain or link to copyright and other legal statements as provided in the “TDWG Standards Documentation Specification”. Copyright notices are required because:
• The copyright gives TDWG the right to publish the whole document as-is in perpetuity;
• The copyright allows others to republish the whole document as-is without obtaining permission (e.g., a document repository or mirror site);
• The copyright permits translation of the whole document into other languages;
• The copyright permits the development of derivative works within the TDWG process and
• All other rights are retained by the authors.
The author proposes that a firm base for TDWG standards efforts can be built by differentiating between the three core document types and adoption of the “TDWG Standards Documentation Specification”.
Study of the Internet Engineering Task Force (IETF), the World Wide Web Consortium (W3C), the Institute of Electrical and Electronics Engineers (IEEE), the Open Geospatial Consortium (OGC) and the Object Management Group (OMG) indicates the following is best practice in relation to documentation:
1. The organisation uses documents as primary outputs.
2. The organisation has clearly specified its documentation process.
3. The specification of documentation is included within the standards process itself to allow for controlled evolution.
4. Clear documentation templates and style guidelines are provided.
5. Clear IP and copyright policies are used.
It would be to the benefit of TDWG to have a documentation strategy that supports best practise. Such a strategy has been developed. It is based on three kinds of document.
Type 1 Documents are the normative parts of a standard. Examples of Type 1 documents are XML Schemas, human readable specifications that must be followed for compliance and controlled vocabularies. Type 1 documents are controlled by the TDWG standards process and are highly stable once ratified.
Type 2 Documents are parts of the standard that are non-normative (informative). Examples of Type 2 documents include examples, code and illustrations that accompany and clarify the standard. As parts of a standard they are also controlled by the TDWG standards process and are highly stable but not normative. The normative documents have precedence over them.
Type 3 Documents are those that fall outside the standard. Examples of Type 3 documents are tutorials, guides, primers, Wikis and discussion forums.
A “TDWG Standards Documentation Specification” has been developed and is proposed as a new TDWG standard to govern TDWG standards (Type 1 and Type 2 documents) going forward. It stipulates that standards take the form of a logical folder or directory that may contain any number of files and may be distributed as a zip or tar archive file. Human readable parts of standards should follow a specified layout and best practice style guidelines. They should be in XHTML format. Normative documents must be in English.
At a minimum, each standard must contain:
• The normative (prescriptive) form of the standard itself (e.g., XML Schema or human readable text);
• A 'Cover Page' document that summarizes the content of the standard but should also contain information on the 'Motivation' for the existence of the standard and the 'Rationale' for why the standard takes the form it does.
Documents should contain or link to copyright and other legal statements as provided in the “TDWG Standards Documentation Specification”. Copyright notices are required because:
• The copyright gives TDWG the right to publish the whole document as-is in perpetuity;
• The copyright allows others to republish the whole document as-is without obtaining permission (e.g., a document repository or mirror site);
• The copyright permits translation of the whole document into other languages;
• The copyright permits the development of derivative works within the TDWG process and
• All other rights are retained by the authors.
The author proposes that a firm base for TDWG standards efforts can be built by differentiating between the three core document types and adoption of the “TDWG Standards Documentation Specification”.