Browser-viewable distributions should be generated for every standards document
baskaufs opened this issue · 3 comments
In a number of cases, standards documents are available only in formats that are not directly viewable in a browser. For example the LSID and GUID AS are Word documents. In some older standards, only the text files with wiki markup are available (not properly rendered). At a minimum, PDFs of these documents should be generated, but optimally they would be converted to MarkDown for easier maintenance. At the same time this is done, the documents should be updated to conform to the SDS, including appropriate licensing information, permanent document URIs, links to previous versions, abstracts, etc. When this is done the accessUrl entries in the metadata table should be updated to point to the new web browser-viewable versions.
There are also some document accessUri's that currently point to pages outside TDWG that contain information about how to access the documents. Since TDWG doesn't control those pages, they will probably never conform to the SDS. So we should think about whether to create our own information pages within the TDWG Github site to describe the status of the document and how to access them. @peterdesmet
Relevant to initial comment, LSID and GUID AS are now viewable online. In the standards landing page build script, documents that are part of a standard are described, eliminating the need to create separate pages for them.
Every standards document should have a form that is easily viewable by humans. However, there are three HTML documents described in the documents metadata table that are only served from GitHub proper (as opposed to GitHub Pages). Since GitHub does not render HTML documents in its page viewer (for example this) and serves raw html documents with a Content-Type header of text/plain (for example this), there isn't any easy way for viewers to see these three pages rendered properly. As a workaround, I've used rawgit links (for example this) to make the pages viewable, but that is not a long-term solution since rawgit will probably go down after October. Ultimately, any documents in this situation should be moved somewhere onto the GitHub pages site so that they will render properly. The standards involved are HISPID3 (the main specification), an ABCD document linked in a Note (that possibly should or should not be included as a standards document), and an SDD document linked in a note (that possibly should or should not be included as a standards document).
The redirect URLs for GUID and LSID have been changed to the PDF versions for the next version. Also, there is now an alternative to rawgit called https://raw.githack.com/ and the unrendered HTML files are now being viewed through that site. So the most critical problems in this issue have been addressed. There still needs to be an overall review and cleanup of documentation, but that's bigger than this issue.