Where do we keep documents, how do people find them, and how do people look at them?

[baskaufs]

@infrastructure This issue came to mind during discussion of the issue 10 of the GitHub tdwg.org tracker [1]. Also relevant are issue 1 about the standards section of the TDWG website [2] and issue 4 [3]. Basically, the issue relates to the kinds of documents that MUST be maintained permanently as a requirement of the standards process.

The TDWG website has a page [4] that describe a 2007 vision for how various types of documents should be stored. Some of what this page talks about is currently non-functional (TDWG Wiki, TDWG website). However, a "Standards Repository" and "rs.tdwg.org" are still relevant. Formerly, the "standards repository" was managed using the TDWG Open Journal Systems (OJS) [5], particularly the "TDWG Standards Track journal" which was used to "manage the submission, review, and ratification of all TDWG standards" but is not publicly viewable. The current instructions for review managers describes how the OJS is used to archive all of the drafts of the developing standard as well as official communications related to the progress of the standards along the Standards Track [6].

The OJS system is difficult to use and flawed in that it is possible to actually delete a standard from the permanent repository (it happened with the TAPIR standard). It also mixes the archiving of confidential documents such as anonymous reviews with documents that should be publicly viewable, such as drafts of the standard that should be on view for public review.

Currently, some of these flaws are being fixed as the TDWG GitHub site is being built, since version control is built-in. It is probably out of scope for a vocabulary maintenance standard to specify any specific places where documents must be stored. However, it seems like the maintenance standard should specify that there be a publicly viewable, version-controlled standards repository where stable, immutable copies of all versions of the standards documents can be stored and retrieved.

Another deficiency of the existing system is that some standards, e.g. the GUID Applicability Statement [7], cannot be directly viewed on the web. Rather, a zip file has to be downloaded and unpacked and then appropriate software (Microsoft Word) has to be used to look at the standard. It should be easily possible for any potential user of a standard to go to a web link and find out the details of the standard and how to use it. We have this for Audubon Core [8] and Darwin Core [9]. However, if it weren't for Google, most people wouldn't be able to find them from the TDWG website. For that reason, I think that it's important that we maintain the permanent URLs of standards (e.g. http://www.tdwg.org/standards/450/ for Darwin Core) so that they are stable and citable. The permanent URL should contain (or redirect to a page containing) links to the permanent repository for the standard and the human viewable webpage. The page http://www.tdwg.org/standards/ should be stable and always link to these permanent URLs.

I'm not sure what to think about rs.tdwg.org . [4] says that that "this is a space for hosting documents that will be accessed by machines. It is principally not for human readable documentation". I think this may be obsolete. The Darwin Core web documents are in that subdomain, but I think they just redirect to somewhere (GitHub now?) anyway. Are there actually commonly accessed machine-viewable documents there? Does it matter? Is it in scope for the vocabulary maintenance standard to specify that machine readible documents have to be in a particular place?

What about the archiving of non-public documents related to the development of the standard (e.g. communication between the review manager and executive and anonymous reviews)? These items provide useful background for new review managers who don't know how to go about the process of shepherding a standard through the TDWG Process and are critical if a review manager must be replaced before the standard is adopted (as happened with Audubon Core). I think this is probably out of scope for the vocab maintenance standard itself, but should probably be dealt with as part of the revamping of the TDWG infrastructure. Also, if the OJS is dumped as part of the rebuild of the TDWG website, what happens to the archived documents related to the adoption of Darwin Core and Audubon Core?

[1] tdwg/infrastructure#10
[2] tdwg/infrastructure#1
[3] tdwg/infrastructure#4
[4] http://www.tdwg.org/activities/documentation/
[5] http://www.tdwg.org/ojs/
[6] http://www.tdwg.org/activities/tasks/ojs/how-standards-track-works/
[7] http://www.tdwg.org/standards/150/
[8] http://terms.tdwg.org/wiki/Audubon_Core
[9] http://rs.tdwg.org/dwc/

[baskaufs]

Should have also referenced Recommendations 5.7, 5.8, and 5.9 of the Report of the VoMaG [10] which discuss publication of machine-readable expressions, translations, and the creation of a "resources browser" that would allow a user to search/browse TDWG vocabularies.

[10] http://www.gbif.org/resource/80862 and https://github.com/tdwg/vocab/blob/master/gbif_TDWG_Vocabulary_Management_Task_Group_en_v1.0.pdf

[peterdesmet]

Thanks @baskaufs for summarizing all of this. I'd also like to point out these related comments on other issues:

• Example of how GitHub releases can serve as immutable versions
• Suggested guidelines on how to use the permanent URLs

[baskaufs]

There is now a document in the infrastructure repository that includes guidelines for handling the permanent URLs for standards.

[baskaufs]

Blocked on Issue #14

[baskaufs]

Added label "documentation" as this issue is relevant to VoMaG Report Recommendation 2.12 that recommends the Documentation Standard include guidelines for creation of ancillary websites that allow questions, comments, and examples.

[baskaufs]

Reference Recommendation 3.1 of the VoMaG report which recommends http://terms.tdwg.org as the preferred community platform for maintaining TDWG vocabularies. Is it in scope for a standards document to specify a particular platform for vocabulary development? Is it in scope to specify that the documentation that is not part of the standard should be found at a specific URI (i.e. http://terms.tdwg.org)?

[baskaufs]

Block on Issue #15 Issue 15 closed.

[baskaufs]

Progress on this issue was made at the 2015-07-15 TG meeting where we discussed draft models for versioning and relating the components of vocabulary standards. Both of these would work towards making it easier for humans and machines to find the parts of a standard and to know the historical record through a versioning system.

[baskaufs]

I think to a large extent this issue has been dealt with now that nearly all standards-related materials have been moved to the TDWG GitHub repo and since the draft documentation specification describes how versioning, content-negotiation, and distributions should be handled. However, I'm going to leave this issue open for now because it's complicated and I think we should continue to think about it in the context of the maintenance spec.

[baskaufs]

Refer also to Issue #40

[baskaufs]

I don't think this issue impacts the development of the draft specifications, so I'm closing it.