Documentation within TDWG

Documentation is central to the development and adoption of standards and so the TDWG Infrastructure Project has developed a Documentation Strategy. It is based on three kinds of document. 

  • Type 1 documents are the normative parts of a standards. 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, discussion forums etc.

A “TDWG Standards Documentation Specification” is a proposed as a new TDWG standard to govern TDWG standards (Type 1and Type 2 documents) going forward. If you are going to submit a new standard you will need to develop the standard documents to this specification.  Other types of documents do not need to follow it.

Less formal templates and documentation approaches have been suggested for Type 3 documents.

  • Charters All subgroups within TDWG must have a charter document that describes their remit and core membership. The collaboration environment provides a forms based application to develop charters.
  • Meeting Reports It is suggested that all TDWG meetings should produce a summary document for general consumption. A word template is provided for this.
  • Primers It is suggested that all TDWG standards be accompanied by an introductory document. This document should be understandable by those not involved in the development standard itself and so provide access to the standard for potential users.

What goes where?

A frequent concern of authors and subgroup conveners is where to put documentation. Under the new collaborative environment four main locations for documents and their functions are clearly demarked.

  1. TDWG Wiki This is the place for anything that is under development or likely to evolve through time. It can be used to collaboratively develop documents and for discussion. Any registered user can edit the wikis.
  2. Main TDWG Website Each subgroup convener has edit rights to the part of the main TDWG website that deals with their subgroup. Outputs of the subgroup (i.e. documents that have been finalised and will not changed) should be uploaded here. This is the 'public face' of the subgroup and is the point that users of standards and new group members will first see. It is therefore important that it presents a unified picture of the subgroups work.
  3. Standards Repository Documents that form parts of formal standards (Types I and II) are stored in the standards repository. When a standard is proposed the documents are loaded into the repository where they are managed through the process of becoming ratified.
  4. This is a space for hosting documents that will be accessed by machines. It is principally not for human readable documentation other than that which forms part of such documents – XSD annotations and RDDL documents for example. Some documents that form parts of a standards will be hosted both here and in the Standards Repository. The ones in the Standards Repository are normative. Experimental documents may also be hosted here during development of standards. Documents in the 'rs' domain may be polled frequently by machines and it is therefore important, for technical reasons, that the space is kept clear of large, rarely accessed documents. Write access to the 'rs' domain is via WebDAV and is controlled by the TDWG environment administrator.
  Last Modified: 06 January 2007