524 lines
38 KiB
Plaintext
524 lines
38 KiB
Plaintext
head 1.6;
|
|
access;
|
|
symbols;
|
|
locks; strict;
|
|
comment @# @;
|
|
|
|
|
|
1.6
|
|
date 2005.12.19.10.48.33; author RogerHyam; state Exp;
|
|
branches;
|
|
next 1.5;
|
|
|
|
1.5
|
|
date 2005.12.05.14.47.59; author RogerHyam; state Exp;
|
|
branches;
|
|
next 1.4;
|
|
|
|
1.4
|
|
date 2005.12.05.10.48.42; author RogerHyam; state Exp;
|
|
branches;
|
|
next 1.3;
|
|
|
|
1.3
|
|
date 2005.12.02.20.00.20; author RicardoPereira; state Exp;
|
|
branches;
|
|
next 1.2;
|
|
|
|
1.2
|
|
date 2005.12.02.12.41.11; author RogerHyam; state Exp;
|
|
branches;
|
|
next 1.1;
|
|
|
|
1.1
|
|
date 2005.11.30.12.28.29; author RogerHyam; state Exp;
|
|
branches;
|
|
next ;
|
|
|
|
|
|
desc
|
|
@none
|
|
@
|
|
|
|
|
|
1.6
|
|
log
|
|
@none
|
|
@
|
|
text
|
|
@%META:TOPICINFO{author="RogerHyam" date="1134989313" format="1.1" version="1.6"}%
|
|
%META:TOPICPARENT{name="DocsDocumentation"}%
|
|
---+ A Documentation and Supporting Software Strategy for TDWG
|
|
|
|
* [[%ATTACHURL%/TDWG_Documenation_and_Supporting_Strategy.doc][TDWG_Documenation_and_Supporting_Strategy.doc]]: The final strategy.
|
|
* [[%ATTACHURL%/TDWG_Documentation_Priorities_2006.doc][TDWG_Documentation_Priorities_2006.doc]]: These are the priorities for documentation for 2006
|
|
* DocsDraftStrategy - the text from the draft strategy document issued in October 2005.
|
|
|
|
|
|
%META:FILEATTACHMENT{name="TDWG_Documenation_and_Supporting_Strategy.doc" attr="" autoattached="1" comment="The final strategy" date="1134989120" path="TDWG_Documenation_and_Supporting_Strategy.doc" size="178688" user="Main.RogerHyam" version=""}%
|
|
%META:FILEATTACHMENT{name="TDWG_Documentation_Priorities_2006.doc" attr="" autoattached="1" comment="" date="1134989150" path="TDWG_Documentation_Priorities_2006.doc" size="50688" user="Main.RogerHyam" version=""}%
|
|
%META:FILEATTACHMENT{name="doc_levels_diagram.jpg" attr="" autoattached="1" comment="Document Levels Diagram" date="1133351005" path="doc_levels_diagram.jpg" size="49049" user="Main.RogerHyam" version=""}%
|
|
@
|
|
|
|
|
|
1.5
|
|
log
|
|
@none
|
|
@
|
|
text
|
|
@d1 1
|
|
a1 1
|
|
%META:TOPICINFO{author="RogerHyam" date="1133794079" format="1.1" version="1.5"}%
|
|
d5 3
|
|
a7 1
|
|
---++ 1 Definitions
|
|
a8 2
|
|
---+++ 1.1 Documentation
|
|
The recording of information to define and support standards in a permanent format .
|
|
d10 3
|
|
a12 239
|
|
---+++ 1.2 Supporting Software
|
|
Supporting software includes reference implementations, test suits and code libraries - specific tools for specific standards. It is separate from the collaboration environment which is used to develop the standards.
|
|
|
|
---++ 2 Current Best Practice
|
|
Study of other standards bodies (see Appendix B) indicates the following best practice:
|
|
1 The organisation is document focused: uses documents as primary outputs.
|
|
1 The organisation has clearly documented documentation process.
|
|
1 The documentation of documentation is included within the process itself to allow for controlled evolution through time.
|
|
1 Clear documentation templates and style guidelines are provided.
|
|
1 Clear IP and copyright policies are in place and used.
|
|
|
|
---++ 3 TDWG Requirements
|
|
The following recommendations are made to bring TDWG into line with current best practice. These recommendations are made on the basis of current TDWG standards (Appendix A) and current best practice (Appendix B).
|
|
|
|
---+++ 3.1 All TDWG standards should be represented as a folio of documents.
|
|
At a minimum, each standard should contain:
|
|
1 The normative(prescriptive) form of the standard itself. (e.g. XML Schema).
|
|
1 A 'Cover Page' document that summarises the content and history of the standard.
|
|
1 A 'Motivations' document that describes the reasons for the standards existence.
|
|
1 A 'Rationale' document that describes why the standard takes the form it does.
|
|
1 A 'Change History' document that describes how this version has changed since the last version.
|
|
|
|
---++++ 3.1.1 Justification.
|
|
For archival purposes it is not sufficient to preserve the original standard document alone as this document can only be interpreted in context. This is especially the case when standards take the form of XML Schema documents.
|
|
1 The standard must defined as an archival document.
|
|
1 For standards to be treated uniformly there must be a document containing metadata in a uniform, machine processable manner.
|
|
1 The potential implementer of a standard must know why the standard exists. This provides the justification for its adoption.
|
|
1 The revisers of a standard cannot understand the intent of original creators without some knowledge of the rational behind the design decisions taken. Without a rational document they are likely to introduce errors.
|
|
1 Implementors of a standard need to know how it differs from previous versions of the same standard so they can adapt their implementation.
|
|
|
|
---+++ 3.2. Each TDWG standard should be accompanied by a ladder of documentation that gives easy access to those making implementation decisions at all levels.
|
|
A task group charter is pivotal in defining the documents that will be produced as part of a standard. When the charter is created and accepted by the Executive, it must define a list of documents that will be created as part of the work of the group. The Executive should ensure that documentation is created for managers and supporting agencies as well as developers.
|
|
|
|
---++++ 3.2.1 Justification
|
|
It is unlikely that a third party will see a developing TDWG standard and spontaneously write introductory literature, tutorials and criticisms as would happen with a W3C Draft Recommendation. It is therefore necessary for the TDWG standards to require a minimum level of documentation (see 3.1 above). Without this documentation, standards are less likely to become widely adopted or maintained into the future and TDWG will fail in its mission.
|
|
|
|
|
|
---+++ 3.3. TDWG must attach clear Copyright and Intellectual Property Rights statements to all standards documents.
|
|
|
|
---++++ 3.3.1 Justification.
|
|
Copyright and Intellectual Property matters must be unambiguous. Public sector and not-for-profit organisations are becoming increasingly aware of the value of the intellectual property they possess and expect clear terms on which they will release it. Commercial organisations are unlikely to become involved in development and implementation of standards if ownership is ambiguous. Less scrupulous organisations may try to take ownership of standards through copyright and patenting if they are produced in a legal vacuum. [See 1.2 ]
|
|
|
|
|
|
---+++ 3.4. TDWG standards that are not currently available on-line should be retired.
|
|
---++++ 3.4.1 Justification
|
|
The role of a standards body is to hold and distribute standards. If the standards are not readily available TDWG is not fulfilling its role.
|
|
|
|
|
|
---+++ 3.5. All TDWG standards documentation should be of a structured form and in a limited range of open, archival formats.
|
|
Archives of meetings, instant messengers conversations, email lists and unstructured wikis should not be considered documentation for the purposes of the TDWG standards process.
|
|
|
|
---+++ 3.5.1 Justification
|
|
Feedback from current developers suggests that getting people to review their work is a major issue. Potential users of standards have complained that they find it hard to get information on both managerial and technical aspects of the standards. Simplified, uniform documentation procedures will help in this.
|
|
When TDWG ratifies a standard, it is making a commitment of resources to host that standard, and to migrate it into any future collaborative environment. In order to maintain the viability of this process, TDWG will need to sanction the different formats in which it will accept documentation for particular purposes.
|
|
|
|
|
|
---+++ 3.7. There should be 3 types of documentation
|
|
Type 1 documents are the normative parts of a standard. Type 2 documents are part of the standard that are non-normative. Type 3 documents are not part of the standard and will not be controlled by the TDWG process but will provide help and support to people working with the standard.
|
|
|
|
---++++ 3.7.1 Types of documentation
|
|
The three different types are illustrated in Diagram 1 and Table 1.
|
|
---++++ Diagram 1: Documentation Types
|
|
<img src="%ATTACHURLPATH%/doc_levels_diagram.jpg" alt="doc_levels_diagram.jpg" width='704' height='466' />
|
|
---++++ Table 1: Enumeration of document Types.
|
|
||Type 1|Type 2|Type 3|
|
|
|Normative|Yes|No|No|
|
|
|Part of a standard|Yes|Yes|No|
|
|
|Function|Defines|Explains and justifies|Helps and Supports|
|
|
|Versioned with Standard|Yes|Yes|No|
|
|
|Controlled by TDWG Process|Yes|Yes|No|
|
|
|Document format|Tightly Controlled|Tightly Controlled|Not Controlled|
|
|
|Document content|Tightly Controlled|Loosely Controlled|Not Controlled|
|
|
|Example formats|XML/ RTF/PDF/XSD|XML/RTF/PDF|Wiki/HTML/Word/PDF|
|
|
|Maintained in collaborative infrastructure|Yes|Yes|Sometimes or possibly only as a link.|
|
|
|
|
---++++ 3.7.2 Justification
|
|
It is important that authors and consumers of standards know the status of the document they are to producing or consuming.
|
|
The three types recommended here provide the simplest system for indicating document status.
|
|
|
|
---+++ 3.8. The process group should publish a standards track with a limited range of maturity levels.
|
|
As standards pass along the track they will increase their maturity level. The process document should produce a clear list of maturity levels. As an example W3C have the maturity levels of 'Working Draft', 'Candidate Recommendation', 'Proposed Recommendation' and 'W3C Recommendation'.
|
|
|
|
These levels should be applied to standards and not to individual documents (see 3.1).
|
|
|
|
---++++ 3.8.2 Justification
|
|
It is important that users of standards know the maturity (and therefore possible volatility) of a standard at any point in time.
|
|
Authors of standards need a process to follow to get their standards accepted.
|
|
|
|
---+++ 3.9. All Type 1 documents should be in English using US spellings and grammatical constructs.
|
|
Translations of Type 1 documents may be supplied, but the translations will be treated as either Type 2 or Type 3 documents. The Executive may require the production of Type 2 translations as part of the standard. All Type 2 documents should be in US English possibly with translations. The Executive may require the production of these translations. Type 3 documents may be produced in any language with no requirement for translation.
|
|
|
|
---++++ 3.9.1 Justification
|
|
Having normative documents in a single language avoids problems of differences arising in translation.
|
|
Requiring translation of non-normative documents would be a burden on standards authors but availability of documenation in multiple languages may help with adoption and so should be encouraged where appropriate.
|
|
|
|
---+++ 3.10. All TDWG standards should have the same documentation standards.
|
|
Even if a standard is in the form of a web service, a folio of documents describing the interface to the services and data curation methods should follow the TDWG standards process.
|
|
|
|
---++++ 3.10.1 Justification
|
|
Any variation would impose a burden on curation and use of the standards.
|
|
|
|
---+++ 3.11. Six standards should be created to initialise the TDWG process.
|
|
Documentation within TDWG should be controlled by standards that are themselves controlled by the standards process (see Best Current Practice point 3 above). In order to do this the first standards to be created must be those that govern documentation. These standards need to be passed simultaneously because they depend on each other. As an example: You can't create a document template standard if the standard that governs the file name to use has not been passed but the file name standard will have to follow the document template so it can't be created either. Six standards have been identified as being the minimum required to bootstrap the process.
|
|
1. File Formats: The file formats, naming and versioning conventions used in all TDWG standards.
|
|
2. Cover Page Specification: The format of the cover page document that should accompany every standard. This will be an XML Schema document.
|
|
3. Layout Template: A specification of how human readable documents should be laid out including the minimum metadata fields such as IPR and Copyright statements.
|
|
4. Process Document: A document specifying how the TDWG process track is administered. This document will include a list of standards maturity levels.
|
|
5. Copyright Notice: The text of a copyright notice to be used on TDWG standards documents along with notes on how it may or may not be modified.
|
|
6. Intellectual Property Statement: Guidelines for inclusion of Intellectual Property Rights statements in TDWG standards documents.
|
|
|
|
These standards must be treated like any other standards (see 3.10) and must contain the minimum documents required i.e. Standard, Cover Page, Motivation, Rational, Change History.(see 3.1)
|
|
|
|
---++++ 3.11.1 Justification
|
|
The documentation process will be controlled by the standards process.
|
|
To initialise the system the first documents through the standards process must be those that control the documentation.
|
|
These are the minimum documents required to initialise the standards track.
|
|
|
|
---+++ 3.12. Task team charters should explain how systems can test whether they comply with the proposed standard.
|
|
Testing will usually take the form of producing compliance test suite of some kind. In the case of XML Schemas the schema itself could be considered the test suite in the case of exchange protocols the test suites are likely to be more complex and require _Supporting Software_. Two independent teams must develop the systems that are subsequently used to test each other.
|
|
|
|
---++++ Justification
|
|
A compliance test suite is a series of procedures or software applications that can be applied to a system to test whether it meets
|
|
a particular standard. Most TDWG standards have had intrinsic compliance testing. The paper-based data standards are lists of facts.
|
|
Compliance is trivial. If the abbreviation is not in the list then it isn't compliant.
|
|
The newer XML Schema based standards are test suites.
|
|
By definition, if an XML document validates against a schema then it is compliant with the standard.
|
|
As more complex standards, such as exchange protocols are ratified, the need for compliance testing will increase.
|
|
Compliance is central to other standards organisations like OGC (http://www.opengeospatial.org/resources/?page=testing).
|
|
|
|
---+++ 3.13. The TDWG process should encourage the development of reference implementation supporting software for standards by requiring it as part of the task group charter, where it is appropriate.
|
|
Compliance test suites should be required alongside reference implementations to show that they conform to the standard. In some situations (such as data exchange protocols and schemas) it may be possible to have two reference implementations that act as compliance tests for each other.
|
|
|
|
---++++ 3.13.1 Justification
|
|
A reference implementation is an example system where software is used to demonstrate a standard. There are three specific ways reference implementations can help the standards process.
|
|
1 The most powerful barrier to reaching consensus on a standard is the criticism “it will never work”. A reference implementation – demonstrating that it does work - is the most effective way to counter this argument.
|
|
1 A reference implementation is perhaps the most effective Level 3 documentation. “A standard is much easier to understand with a working example in hand.” (http://en.wikipedia.org/wiki/Reference_implementation)
|
|
1 A reference implementation demonstrates the independence of the standard from an implementation.
|
|
|
|
---+++ 3.14. If TDWG is to ensure quality control of data being served dynamically four things must happen:
|
|
1. Documents need to be created that describe the interface to the data and how the data will be curated. These documents must go through the TDWG standards track.
|
|
2. Supporting software needs to be provided that will serve the data in the way specified in the documentation. This software may be hosted by TDWG or a third party.
|
|
3. Test software needs to be created that will regularly monitor that data is being served in a way that is compliant with the documentation. This has to be hosted by TDWG or on TDWG's behalf.
|
|
4. Demonstration client software needs to be created to demonstrate how to use the service.
|
|
|
|
---++++ 3.14.1 Justification
|
|
Botanical author abbreviations and herbarium codes are examples of TDWG data standards that are now databases.
|
|
If these databases are to be ratified as TDWG standards, either static, versioned snapshots need to be released as regular standard documents, or the dynamic data has to be served in a controlled way.
|
|
There appears to be little interest in formalising older TDWG standards, but this situation could soon change with the introduction of Globally Unique Identifiers.
|
|
TDWG may need to ratify standard lists such as herbaria or entomological collections. The TDWG Process should handle these cases.
|
|
|
|
---+ Appendix A: Review of Current Standards Documentation
|
|
---++ 1 Mature Standards:
|
|
* Authors of Plant Names: A book listing plant name authors and approved abbreviations published in 1992. Now integrated into International Plant Names Index. Help text associated with on-line searches.
|
|
* Botanical Periodicals: A list of botanical periodicals. Published 1968 with supplement 1991. Currently out of print.
|
|
* Economic Botany Data Collection Standard: A book published in 1995. Still in print.
|
|
* XDF: A language for the definition and exchange of biological data sets.
|
|
* Floristic Regions of the World: A section of a book published in 1986. Now out of print.
|
|
* Geographical Codes: A book published in 1992 and updated in 2001(not clear if 2001 version is ratified by TDWG). Polygons of listed regions have been made available by Kew but not been put forward for ratification by TDWG. (http://www.tdwg.org/geo2.htm)
|
|
* Herbarium Index Codes: A book published in 1990. Now maintained as an on-line database. Not clear if on-line version is TDWG standard. Help text associated with on-line searches. (http://sciweb.nybg.org/science2/IndexHerbariorum.asp)
|
|
* Herbarium Information Standards and Protocols for Interchange of Data. Available as a document on-line or in print. Latest version available as a searchable database. (http://plantnet.rbgsyd.nsw.gov.au/HISCOM/HISPID/HISPID3/hispidright.html)
|
|
* Plant Names in Botanical Databases: A 1995 publication available on-line (http://www.tdwg.org/plants.html)
|
|
* Publication Abbreviations: A book series started in 1976.
|
|
* Plant occurrence and status scheme: A document published in 1995 and available on-line (http://www.tdwg.org/poss_standard.html).
|
|
* DELTA (Description Language for Taxonomy): User guide published in 1986 with subsequent updates. Much available on line though linked to a particular implementation (http://delta-intkey.com/)
|
|
---++ 2 Newly Adopted Standards:
|
|
* ABCD: XML Schema, schema annotations, misc pdf documentation, database of 'concepts' used within the schema. (http://www.bgbm.org/TDWG/CODATA/ABCD-Versions.htm & http://ww3.bgbm.org/abcddocs/AbcdIntroduction)
|
|
* SDD: Extensive Wiki documentation and discussion including an initial draft of a 'Primer' document to get people started. Authors have difficulty keeping documentation up to date. (http://bdei.cs.umb.edu/twiki/bin/view/SDD/WebHome)
|
|
* Taxon Concept Schema: XML Schema, schema annotations exported as html, user guide as pdf, development wiki. (http://www.soc.napier.ac.uk/tdwg/index.php)
|
|
|
|
|
|
---+ Appendix B:Documentation Best Practice in Other Similar Standards Organisations
|
|
|
|
---++ Summary
|
|
Best practice in terms of the overall quality of documentation appears to be between W3C and IETF. Other bodies tend to copy these two organisations, but each organisation has some useful lessons for TDWG. It is regrettable that a number of other standards organisations do not make their documentation freely available.
|
|
|
|
The GGF strategy is notable and appealing
|
|
|
|
Documentation of documentation + open document formats = best practice.
|
|
---++ Global Grid Forum
|
|
* http://www.ggf.org/index.php
|
|
* First document in series sets out documentation requirements (http://www.ggf.org/documents/GFD.1.pdf)
|
|
* Authors strongly encouraged to follow IETF Internet Drafts format where possible
|
|
* Documents must contain:
|
|
* Document type: GWD-X or GFD-X, where X is one of several types including I(informational), E (experimental), P (Community Practice), or R (Recommendations track).
|
|
* Author name(s), affiliation(s), and contact information
|
|
* Date of the document (original date and revised date).
|
|
* Name of working group or research group (where applicable)
|
|
* Title of document
|
|
* Document URL
|
|
* 1-2 paragraph abstract
|
|
* a summary of security considerations.
|
|
Institute of Electrical and Electron Engineers
|
|
* http://www.ieee.org/portal/site
|
|
* Difficult to find out much about as this group appear largely commercial.
|
|
Internet Engineering Task Force
|
|
* http://www.ietf.org/
|
|
* Detailed document describing document formatting (http://www.ietf.org/ietf/1id-guidelines.html)
|
|
* ASCII text only for standard documents.
|
|
* May have accompanying (but non-normative documents).
|
|
* Documents are the standards.
|
|
* Strong on IP issues.
|
|
International Multimedia Telecommunications Consortium
|
|
* http://imtc.org/
|
|
* Does not produce standards of its own but works with other bodies notably IETF.
|
|
International Organisation for Standardization
|
|
* http://www.iso.org/iso/en/ISOOnline.frontpage
|
|
* Over 14,000 standards and long history.
|
|
* Documents are the standards.
|
|
* Detailed documentation for docs (http://isotc.iso.org/livelink/livelink/fetch/2000/2122/3146825/4229629/texts_list.htm)
|
|
Organization for the Advancement of Structured Information Standards
|
|
* http://www.oasis-open.org/home/index.php
|
|
* "A specification may be composed of any number of files of different types, though any such multi-part specification must have a single specification name and version number. Irrespective of the number and status of the constituent parts, the specification as a whole must be approved by a single TC ballot. "
|
|
* "All documents and other files produced by the TC, including specifications at any level of approval, must use the OASIS file naming scheme, and must include the OASIS copyright notice. All document files must also use the OASIS document templates." (http://docs.oasis-open.org/templates/)
|
|
* Templates are provided for working in MS Word, OpenOffice? and XHTML.
|
|
Open Geospatial Consortium
|
|
* http://www.opengeospatial.org/
|
|
* Released as PDF (and white papers as Word docs).
|
|
* Appears to be a clear format/template used.
|
|
* Can't find documentation on website (may be members only)
|
|
Web Services Interoperability Organisation
|
|
* http://www.ws-i.org/
|
|
* Issue documents are PDF
|
|
* Standards ('deliverables') include software.
|
|
* Supply MS Word templates for creation of documents.
|
|
* Document format is very similar to W3C format.
|
|
* Details may be in members only area.
|
|
World Wide Web Consortium
|
|
* http://www.w3.org/
|
|
* Well defined document rules (http://www.w3.org/2005/07/pubrules)
|
|
* Well defined style (http://www.w3.org/Provider/Style/)
|
|
* Well defined help on authoring documents (http://www.w3.org/2001/06/manual/)
|
|
* Some guides only available to members (http://www.w3.org/Guide/Reports)
|
|
|
|
|
|
-- Main.RogerHyam - 30 Nov 200.
|
|
|
|
|
|
|
|
%META:FILEATTACHMENT{name="doc_levels_diagram.jpg" attachment="doc_levels_diagram.jpg" attr="" comment="Document Levels Diagram" date="1133351005" path="doc_levels_diagram.jpg" size="49049" stream="doc_levels_diagram.jpg" user="Main.RogerHyam" version="0"}%
|
|
@
|
|
|
|
|
|
1.4
|
|
log
|
|
@none
|
|
@
|
|
text
|
|
@d1 1
|
|
a1 1
|
|
%META:TOPICINFO{author="RogerHyam" date="1133779722" format="1.1" version="1.4"}%
|
|
d15 5
|
|
a19 5
|
|
* The organisation is document focused: uses documents as primary outputs.
|
|
* The organisation has clearly documented documentation process.
|
|
* The documentation of documentation is included within the process itself to allow for controlled evolution through time.
|
|
* Clear documentation templates and style guidelines are provided.
|
|
* Clear IP and copyright policies are in place and used.
|
|
d22 1
|
|
a22 1
|
|
The following recommendations are made on the basis of current TDWG standards (Appendix A) and current best practice (Appendix B).
|
|
d26 5
|
|
a30 5
|
|
1. The normative form of the standard itself. (e.g. XML Schema).
|
|
2. A 'Cover Page' document that summarises the content and history of the standard.
|
|
3. A 'Motivations' document that describes the reasons for the standards existence.
|
|
4. A 'Rationale' document that describes why the standard takes the form it does.
|
|
5. A 'Change History' document that describes how this version has changed since the last version.
|
|
d34 5
|
|
a38 1
|
|
* Fixme - each one justified
|
|
d53 1
|
|
a53 1
|
|
---+++ 3.4. TDWG standards that are not available on-line should be retired.
|
|
d90 3
|
|
a92 1
|
|
As standards pass along the track they will increase their maturity level. The process document should produce a clear list of maturity levels. These levels should be applied to standards (i.e. the collection of documents composing the standard) and not to individual documents. It should not be possible for documents within a standard to have different maturity levels.
|
|
d111 3
|
|
a113 2
|
|
---+++ 3.11. Six documents should be created to initialise the TDWG process.
|
|
1. File Formats: The file formats, naming and versioning conventions used in TDWG standards.
|
|
d120 2
|
|
d127 2
|
|
a128 2
|
|
---+++ 3.12. Task group charters should explain how systems can test whether they comply with the proposed standard.
|
|
Testing will usually take the form of producing compliance test suite of some kind. In the case of XML Schemas the schema itself could be considered the test suite in the case of exchange protocols the test suites are likely to be more complex and require _Supporting Software_.
|
|
d148 1
|
|
a148 7
|
|
---+++ 3.14. Two independent teams must develop the systems that are subsequently used to test each other.
|
|
Ideally these _Supporting Software_ implementations should also be implemented using different technologies.
|
|
|
|
---+++ 3.14.1 Justification
|
|
The basic principle of reproducability of results dictates that results of a process should only be accepted if two independent entities can reproduce them.
|
|
|
|
---+++ 3.15. If TDWG is to ensure quality control of data being served dynamically four things must happen:
|
|
d153 2
|
|
a154 1
|
|
---++++ 3.15.1 Justification
|
|
@
|
|
|
|
|
|
1.3
|
|
log
|
|
@none
|
|
@
|
|
text
|
|
@d1 1
|
|
a1 1
|
|
%META:TOPICINFO{author="RicardoPereira" date="1133553620" format="1.1" version="1.3"}%
|
|
d11 1
|
|
a11 3
|
|
Supporting software is software that is directly required for the development and deployment of standards. It includes reference implementations, test suits and code libraries. It is separate from the collaboration environment. The collaboration environment provides generic services. Supporting software provides specific tools for specific standards.
|
|
|
|
* _This separation between supporting software and collaboration environment is really tricky. I would say that supporting software is that used as part of one or more implementations of a standard (stretching the concept to include test suits) while collaboration environment is used to develop the standard. But you might as well leave as it is. That is good enough a definition._ -- Main.RicardoPereira - 02 Dec 2005
|
|
d22 1
|
|
a22 1
|
|
The following recommendations are made on the basis of current best practice (Appendix B) and current TDWG standards (Appendix A).
|
|
d34 1
|
|
a34 1
|
|
|
|
@
|
|
|
|
|
|
1.2
|
|
log
|
|
@none
|
|
@
|
|
text
|
|
@d1 1
|
|
a1 1
|
|
%META:TOPICINFO{author="RogerHyam" date="1133527271" format="1.1" version="1.2"}%
|
|
d13 2
|
|
@
|
|
|
|
|
|
1.1
|
|
log
|
|
@none
|
|
@
|
|
text
|
|
@d1 1
|
|
a1 1
|
|
%META:TOPICINFO{author="RogerHyam" date="1133353709" format="1.1" version="1.1"}%
|
|
d7 2
|
|
a8 2
|
|
---++ 1.1 Documentation
|
|
The recording in a permanent format of information to define and support standards.
|
|
d10 1
|
|
a10 1
|
|
---++ 1.2 Supporting Software
|
|
d13 7
|
|
a19 1
|
|
---++ 2 Requirements
|
|
d21 4
|
|
a24 1
|
|
---+++ 2.1 All TDWG standards should be represented as a folio of documents.
|
|
d32 3
|
|
d36 1
|
|
a36 2
|
|
---+++ 2.2. TDWG must attach clear Copyright and Intellectual Property Rights statements to all standards documents.
|
|
---+++ 2.3. Each TDWG standard should be accompanied by a ladder of documentation that gives easy access to those making implementation decisions at all levels.
|
|
d38 17
|
|
a54 3
|
|
---+++ 2.4. TDWG standards that are not available on-line should be retired.
|
|
The role of a standards body is to hold standards. If the standards are not readily available TDWG is not fulfilling its role.
|
|
---+++ 2.5. All TDWG standards documentation should be of a structured form.
|
|
d56 2
|
|
a57 34
|
|
---+++ 2.6. All TDWG standards documentation should be in a limited range of open, archival formats.
|
|
---+++ 2.7. There should be 3 Levels of documentation
|
|
Level 1 documents are the normative parts of a standard. Level 2 documents are part of the standard that are non-normative. Level 3 documents are not part of the standard and will not be controlled by the TDWG process but will provide help and support to people working with the standard.
|
|
---+++ 2.8. The process group should publish a standards track with a limited range of maturity levels.
|
|
As standards pass along the track they will increase their maturity level. The process document should produce a clear list of maturity levels. These levels should be applied to standards (i.e. the collection of documents composing the standard) and not to individual documents. It should not be possible for documents within a standard to have different maturity levels.
|
|
---+++ 2.9. All Level 1 documents should be in English using US spellings and grammatical constructs.
|
|
Translations of Level 1 documents may be supplied, but the translations will be treated as either Level 2 or Level 3 documents. The Executive may require the production of Level 2 translations as part of the standard. All Level 2 documents should be in US English possibly with translations. The Executive may require the production of these translations. Level 3 documents may be produced in any language with no requirement for translation.
|
|
---+++ 2.10. All TDWG standards should have the same documentation standards.
|
|
Even if a standard is in the form of a web service, a folio of documents describing the interface to the services and data curation methods should follow the TDWG standards process.
|
|
---+++ 2.11. Six documents should be created to initialise the TDWG process.
|
|
This document is a bootstrap document and so does not form part of the standards process. Six documents are required to initialise the documentation process.
|
|
1. File Formats: The file formats, naming and versioning conventions used in TDWG standards.
|
|
2. Cover Page Specification: The format of the cover page document that should accompany every standard. This will be an XML Schema document.
|
|
3. Layout Template: A specification of how human readable documents should be laid out including the minimum metadata fields such as IPR and Copyright statements.
|
|
4. Process Document: A document specifying how the TDWG process track is administered. This document will include a list of standards maturity levels.
|
|
5. Copyright Notice: The text of a copyright notice to be used on TDWG standards documents along with notes on how it may or may not be modified.
|
|
6. Intellectual Property Statement: Guidelines for inclusion of Intellectual Property Rights statements in TDWG standards documents.
|
|
---+++ 2.12. Task group charters should explain how systems can test whether they comply with the proposed standard.
|
|
Testing will usually take the form of producing compliance test suite of some kind. In the case of XML Schemas the schema itself could be considered the test suite in the case of exchange protocols the test suites are likely to be more complex.
|
|
---+++ 2.13. The TDWG process should encourage the development of reference implementations for standards by requiring it as part of the task group charter, where it is appropriate.
|
|
Compliance test suites should be required alongside reference implementations to show that they conform to the standard. In some situations (such as data exchange protocols and schemas) it may be possible to have two reference implementations that act as compliance tests for each other.
|
|
---+++ 2.14. Two independent teams must develop the systems that are subsequently used to test each other.
|
|
Ideally these implementations should also be implemented using different technologies.
|
|
---+++ 2.15. If TDWG is to ensure quality control of data being served dynamically four things must happen:
|
|
1. Documents need to be created that describe the interface to the data and how the data will be curated. These documents must go through the TDWG standards track.
|
|
2. Software needs to be provided that will serve the data in the way specified in the documentation. This software may be hosted by TDWG or a third party.
|
|
3. Test software needs to be created that will regularly monitor that data is being served in a way that is compliant with the documentation. This has to be hosted by TDWG or on TDWG's behalf.
|
|
4. Demonstration client software needs to be created to demonstrate how to use the service.
|
|
|
|
---++ 3. Justification
|
|
A review of Current TDWG standards documentation and examples of the approaches taken by other organisations are given in appendices A and B.
|
|
---+++ 3.1. Why should TDWG standards be composed of multiple documents?
|
|
It is unlikely that a third party will see a developing TDWG standard and spontaneously write introductory literature, tutorials and criticisms as would happen with a W3C Draft Recommendation. It is therefore necessary for the TDWG standards to require a minimum level of documentation. Without this documentation, standards are less likely to become widely adopted or maintained into the future and TDWG will fail in its mission. [See 1.1]
|
|
---+++ 3.2. Why should documentation be in set structures and formats?
|
|
d59 9
|
|
a67 6
|
|
When TDWG ratifies a standard, it is making a commitment of resources to host that standard, and to migrate it into any future collaborative environment. In order to maintain the viability of this process, TDWG will need to sanction the different formats in which it will accept documentation for particular purposes. [See 1.5 an 1.6]
|
|
---+++ 3.3. Why is Copyright and IPR important?
|
|
Copyright and Intellectual Property matters must be unambiguous. Public sector and not-for-profit organisations are becoming increasingly aware of the value of the intellectual property they possess and expect clear terms on which they will release it. Commercial organisations are unlikely to become involved in development and implementation of standards if ownership is ambiguous. Less scrupulous organisations may try to take ownership of standards through copyright and patenting if they are produced in a legal vacuum. [See 1.2 ]
|
|
---+++ 3.4. What are the three document levels?
|
|
The three different levels are illustrated in Diagram 1 and Table 1.
|
|
---++++ Diagram 1: Documentation Levels
|
|
d69 2
|
|
a70 2
|
|
---++++ Table 1: Enumeration of document levels.
|
|
||Level 1|Level 2|Level 3|
|
|
d81 31
|
|
d113 21
|
|
a133 3
|
|
---+++ 3.5. Why is compliance testing needed?
|
|
A compliance test suite is a series of procedures or software applications that can be applied to a system to test whether it meets a particular standard. Most TDWG standards have had intrinsic compliance testing. The paper-based data standards are lists of facts. Compliance is trivial. If the abbreviation is not in the list then it isn't compliant. The newer XML Schema based standards are test suites. By definition, if an XML document validates against a schema then it is compliant with the standard. As more complex standards, such as exchange protocols are ratified, the need for compliance testing will increase. Compliance is central to other standards organisations like OGC (http://www.opengeospatial.org/resources/?page=testing). [See 1.12]
|
|
---+++ 3.6. Why are reference implementations needed?
|
|
d135 6
|
|
a140 6
|
|
a. The most powerful barrier to reaching consensus on a standard is the criticism “it will never work”. A reference implementation – demonstrating that it does work - is the most effective way to counter this argument.
|
|
b. A reference implementation is perhaps the most effective Level 3 documentation. “A standard is much easier to understand with a working example in hand.” (http://en.wikipedia.org/wiki/Reference_implementation)
|
|
c. A reference implementation demonstrates the independence of the standard from an implementation.
|
|
See [1.13]
|
|
---+++ 3.7. Why should TDWG ratify data being served dynamically?
|
|
Botanical author abbreviations and herbarium codes are examples of TDWG data standards that are now databases. If these databases are to be ratified as TDWG standards, either static, versioned snapshots need to be released as regular standard documents, or the dynamic data has to be served in a controlled way. There appears to be little interest in formalising older TDWG standards, but this situation could soon change with the introduction of Globally Unique Identifiers. TDWG may need to ratify standard lists such as herbaria or entomological collections. The TDWG Process should handle these cases. [See 1.15]
|
|
d142 14
|
|
d157 1
|
|
a157 1
|
|
---++ 1 Current Standards:
|
|
d170 1
|
|
a170 1
|
|
---++ 2 Proposed Standards:
|
|
d175 5
|
|
a179 6
|
|
---+ Appendix B: Documentation in Other Standards Bodies – Best Practice
|
|
In contrast to TDWG, most successful standards bodies are focussed on documents and managing them.
|
|
* One of the primary purposes of the Global Grid Forum (GGF) is to publish documents. These documents provide information and specifications to developers and others involved with Grid computing.” The Global Grid Forum (http://www.ggf.org/)
|
|
* Specifications are simply engineering documents that describe how the OGC membership has agreed to solve an interoperability problem.” Open Geospatial Consortium (http://www.opengeospatial.org)
|
|
* The W3C working groups are principally involved in moving a 'technical report' document along the Recommendation Track to becoming a W3C Recommendation. (http://www.w3.org/2004/02/Process-20040205/)
|
|
Organization for the Advancement of Structured Information Standards (OASIS) use documents to drive their Technical Committee Process. (http://www.oasis-open.org/committees/process.php)
|
|
d181 59
|
|
@
|