TDWG Standards Documentation Specification (Cover Page)

Peer Review By Anna Weitzman

This is a well-written document, with all the legal things that I can think of that it should have. To my eye, with a few clarifications that need to be made and minor editorial corrections (noted in the copy I will upload), I think this is ready to go. This should be accepted (for vote) with those clarifications and minor corrections.

Some TDWG members and conveners will undoubtedly see this as overly complex, but I believe that this is the way that TDWG needs to go.

The only further comment that I have is about the definition of Type 3 TDWG documents. It is exactly these documents--including the explanations of how to use TDWG standards, tutorials, background work--including Use Cases, examples of standards in practice and lessons learned by trying to implement the standards, that I believe we should start a TDWG journal for (of course the journal can include any relevant content in addition). Currently there really is no such place, and there should be.

Peer Review By Jessie Kennedy

I have annotated the document with some typos and comments which should be addressed using track changes.

I think the standard fo rdocuments will rely on the tools provided, therefore I don't htink we can really tell how useful or clear this document is until used in conjunction with the tools following the process. I would say accept as is (subject to comments) but request a review by someone going through the process which might help clarify any issues encountered while using it.

Peer Review By Neil Thomson

Overall this is a clear and readable description of the presentation of TDWG standards. This is important for achieving consistency as several standards are approaching this stage in their development.

The only areas that could be considered for some expansion were as follows:

- There is only one mention of RDF and this relates to the metadata for a standard. Given that TDWG is advocating the use of RDF it would be helpful to have RDF examples mentioned more frequently.

- An expanded explanation of the role of rs.tdwg.org would be useful. Until recently I was unaware of the requirement to use this as the editing environment, rather than local copies of files, where other namespaces are used.

- Paragraph 14.2.4 is less clear than other areas of the document. If there is a separate document on *how* to submit a standard to TDWG, some reference to it would be useful in this document. Otherwise the "two unrelated implementations" and "significant implementation" need further explanation.

- A couple of details: where should these files be deposited or to whom should they be presented and who issues the LSID for the standard? As above, these may be addressed in a separate document, which could be usefully cited as a companion.

Other than that, an excellent document that I have no hesitation in recommending.

Peer Review By Walter Berendsohn

On 8 Versioning of Standards
I think that the wording is too strong here: "it must be superseded by a standard with a different name" - the name can be the same name with a different version number.
I also think that we should include an option that, upon informed decision of the Executive Committee, for some forms of standards (e.g. XML schema) **fully compatible** minor updates may be published and replace the original standard’s namespace. (see http://www.tdwg.org/proceedings/article/view/62).

11 Human Readable Documents
Should the cover page document be exempted from the rule that all documents should follow the structure outlined below this heading?

On 11.3 Body Section
"1.1.1 Subsubsection within main section."
should read
"1.1 Subsubsection within main section."

13 Cover Page Contents
Should the Creator / Contributors be formatted as specified under 11.1?

13 Cover Page
Publisher: Should we use TDWG - most likely we will retain at least this of the old name?

13 Cover Page
Replaces: Should be repeatable.

Peer Review By William Ulate

Except for the legal part, it is all very clear and easy to follow. I have made some minor observations that could be attended:

1. Supposedly there is no versioning of standards, as stated in point 8. But then, how would ABCD 1.2 be considered against ABCD 2.06? Could there be something like ABCD 2.06b?

2. This document should be itself presented in one of the acceptable formats specified in point 9.

3. Should the format in which the subheadings are numbered in the example be taken as the way to do it or just an example? For example, could I use a period at the end of the numbering? Is the period the only valid separator in the simple decimal system?

4. Does TDWG define a domain for the keywords and classification codes included in the Subject part of the Cover Page?

5. Should URLs be specified in the Fields for Cover Page documents or would URIs do?

6. It is written that the Has Part section could refer to a URL within the standard. If the Standard “includes” some other existing (external) Standard as a subpart, should it be referenced here or does it have to be copied into this Standard as well?

7. The legal part is way too long and hard to follow. Notes to include within the standard literally should be clearly differentiated.

Peer Review By Bob Morris

It is important that this document be made available to the membership. In a separate word document I include some suggestions and minor objections. The ones marked XXXX seem critical to me, but most of them seem to me to be improvements. Many of the issues arise from not knowing whether this document is itself (meant to be) a Type 1, 2, or 3 document. I'd prefer it to be a Type 1 document and form, together with its required CoverPage, a (proposed?) standard for TDWG standards documentation.

Peer Review By Mark Jackson

Comments on TDWG Standards Documentation Specification

To set the context, this is about how new standards are documented. Existing standards will presumably continue in their various idiosyncratic formats until retired.

Section 3 Documents and Files

Since type 3 documents are specified here, what is TDWG’s attitude to them? Are type 3 documents encouraged and will TDWG host them? Or does TDWG wash its hands of them?

Section 6 Naming

Full name (text). Would it be useful to mandate that “TDWG:” be included, e.g. as a prefix? If not, how could we brand standards so that people for example talk of ‘TDWG 1234’ a la ISO standards? Does this name need to be present on all documents/files?

Since a standard consists of one or more documents which may consist of one or more files, there may need to be some clarity over what a ‘filename’ applies to. My reading of it is that this really is about filenames. If so, how and where should we name documents?

Are we missing a ‘short name’, an abbreviated form of the full name which might be useful in lists, tables, common parlance, etc?

8. Versioning

So, no versions. But it is presumably legal to use very similar names e.g. “Standard X v1” and then Standard X v2”.

9. File Formats

To be open, should we also mention ‘available on standard common computing platforms’ or some such phrase? Section 11 specifies XHTML which is not (strictly) in the list.

11. Human Readable Documents

Presumably here we mean any document which is intended to be primarily or solely human-readable, and not for example an XML schema (which is often human-readable but is really intended for software consumption)?

13 Cover Page Contents

Is the Cover Page a special case of document, e.g. a type 2 human-readable document but exempted from the strictures of section 11? Since the Cover Page is mandated, why not include the motivation and rationale sections (also mandatory according to section 4) within it?

Rights. Why would a document describing the IPR situation typically be “contained within” another standard? This is not intended – the preferred model is to have free-standing documents (see section 14).

Access Rights – we already have a metadata entry for ‘Rights’, so how does this field relate to it? It isn’t clear to me what the term ‘public’ in a field ‘Access Rights’ would mean – ‘public domain’? This can’t be correct given the presence of the ‘Rights’ field. The phrase “freely available to all” is also ambiguous – do you mean without charge, without hindrance, without restrictions? I don’t feel it adds anything, and this should be covered by pages on the TDWG website.

Under Bibliographic Citation – well, how should a standard be cited?

Has Part is the only place I have been able to spot where the constituent parts of a standard are recorded. The word ‘file’ has been used in the definition, but if we are standardising our use of terms, shouldn’t this be ‘document’? We do need to specify somewhere what the standard consists of in terms of documents, but do we also want to record what files make up these documents? I would suggest not. I am reminded of the METS standard which provides a way of defining complex objects, but maybe we don’t want to go that far…

14 Legal Statements

I don’t find this rather lengthy section to be about standards documentation per se, but about how TDWG wishes to handle the IP situation for TDWG standards. I agree TDWG needs to cover IP and legal issues, but I would make this a separate discussion. The current text feels like a “work in progress” and I would want to ask our lawyer for an opinion on it (particularly section 14.2 which is new ground to me).

Anyway, here are some initial reactions:

a) the main subdivision headings seem odd – copyright **is** an intellectual property right, and the given copyright statement repeats the disclaimer.
b) throughout there is mention of ‘this document’ but shouldn’t we be talking of ‘this standard’ so as to avoid multiple and tedious repetition of lengthy legal texts?
c) why not use Creative Commons licenses?

14.1 Copyright

The first bit reads oddly. What is actually happening is that TDWG are claiming the copyright over standards, and are granting everyone else certain rights. This should be stated. Also, the last bullet point isn’t correct – copyright rests with TDWG, not the authors.

I’m no lawyer but the wording of the actual statement looks in need of some attention to me. I don’t have time to suggest something right now, and you probably don’t want me to do this. The first part appears to permit the creation of ‘derivative works’, but this phrase is not defined. Is the idea that this covers situations where you might incorporate large parts of the original in other documents? If so, can we be more direct, e.g. ‘you may incorporate any amount of this document in other documents whose purpose is to comment on or otherwise explain…’ etc.

14.2 Intellectual Property

Wow, do we really need this? I need a legal opinion! Do you want me to see if our lawyer will take a look at it?

Editor's Decision

Hi Stan, Please find attached the latest version of the document that includes the comments from John and Bob and all the rest. Also the text file with the comments in plus my comments on the comments prefixed with RDH: I don't think there is anything major there other than some one mentioning the use of a lawyer which I would find comforting but would probably delay things for ever. Is this ready for public review? I wonder if I should convert it to XHTML and make a more official looking standard out of it if it is. All the best, Roger ________________________________________________________________________ TDWG Standards Track http://www.tdwg.org/stdtrack

Stan, I have cleaned up the word version of the spec. Accepted all the changes to make it readable - especially if people change it some more. I have added this as the latest 'author version'. I hope this is the right procedure. It is fine to send it to the Exec now as far as I am concerned. We can transform it to XHTML and give it it's correct URLs after that. All the best, Roger ________________________________________________________________________ TDWG Standards Track http://www.tdwg.org/stdtrack

Hi Stan, I have gone through 147-483-4-RV.doc and converted it to xhtml with the style developed by Loic (with minor adjustments). I have uploaded this to OJS as 147-543-3-ED.xhtml. I simplified the html code somewhat from Loic's example and added a couple of things to the style sheet so that the xhtml now looks cleaner and simpler should anyone want to edit it with an xml editor. I hope that it is simple enough for some one else who is producing a standard to use it like a kick off template. The style is totally separate from the document and not hosted in the document or standard. If you don't have a network connection when you view this file it will appear OK but totally unbranded. There is a catch (isn't there always). The style sheet and associated documents need to be mounted somewhere web accessible (probably in the rs.tdwg.org space) but I can't get access to that at the moment so I have put them on a hosting space I have for the time being. We will need to change this link once they are in their proper place. Could you look at the new file and see if I have messed anything up. I had my html hackers hat on when I did this and wasn't paying much attention to the words. Bounce it back to me with any problems or change them yourself. I am out of time today. We need to work out how we make this publicly visible for the public to review. Any ideas Lee? Come back Ricardo we need you!! I wonder if we can simplify the standards repository down to being the OJS journal.... Roger ________________________________________________________________________ TDWG Standards Track http://www.tdwg.org/stdtrack