Figure out what documents should actually be considered to be part of a standard
baskaufs opened this issue · 3 comments
It has always been a bit murky determining what documents or files are actually part of a standard. In the past, whatever was zipped up and submitted to the OJS system as an archive for the standard was considered part of the standard. That definition is now useless since the OJS system doesn't really exist any more. Under the new Standards Documentation Specification, a document is considered part of a standard if the metadata for the standard and the document say that it is. However, there isn't any such metadata for at least the human-readable versions of many standards. I've guessed about this when creating the machine-readable metadata, but somebody should go over my list and make sure that there aren't important documents that are missing. For actively maintained standards (AC and DwC), the Maintenance Groups should make the decision as to which documents are parts of the standard and declare that in the human-readable metadata. For older standards, somebody familiar with their use should verify that at least the necessary normative documents are listed. A prime example of this is TAPIR, which has many XML documents whose purpose is not clear to me. I've listed what seem to be the most important ones, but am probably missing some.
The documents that are considered to be part of standards are determined for both machine-readable metadata and on the pages generated by the build script by the table standards-parts.csv.
In many cases, it is obvious what documents should be considered as part of a standard. In the case of standards like DwC and AC, the documents included in the standard are clear because their respective maintenance groups have discussed the issue and decided what documents should be included. In other standards where there are only one or two documents, it is also clear.
For some of the older standards, it's more murky - for example, I was unable to find a copy of the XDF specification anywhere, only a paper describing (but not specifying) XDF. (See Issue #4 ) Since for many standards I arbitrarily decided what documents I thought should be considered as part of the standard, someone should undertake a careful review of each standard to make sure that there are no omissions or incorrect inclusions. This is particularly important for ABCD, SDD, and TAPIR, which contain multiple documents and for which there is little information about what is actually normative/included in the standard itself.
The critical distinction here is that any document that is put on the list as included in the standard should be subject to strict restrictions on changes in order to preserve the stability and interoperability of the standard. Any document not on this list could be changed at will by any individuals tasked with maintaining the standard. Thus, any document containing any normative material should be on the list. In a perfect world, normative content would be declared as required by the SDS, but since we are still trying to get into compliance with the SDS, most older documents don't have this declaration and so someone will have to make a judgement about inclusion.
This item is relevant to Issue #9 , since the three documents I mention there may or may not actually be "part of the standard". If they aren't part of the standard, they are out of scope, but if they are part of the standard, they need to be fixed as described in that issue.
This has been resolved. The documents listed [here in a CSV in the rs.tdwg.org repo]https://github.com/tdwg/rs.tdwg.org/blob/master/docs/docs.csv) are used both to generate the machine readable data about what's included in the standard and also was used in this script that built the standards landing pages linked from https://www.tdwg.org/standards/.