Migrate "TDWG Standards Documentation Specification"

[peterdesmet]

Current URL: http://www.tdwg.org/standards/147/

• [x] Contact someone from the standard task group
• [x] Verify the standard is not maintained in another repository already: it is: https://github.com/tdwg/vocab
• [x] Decide on shortname
• [x] Ask for preferred citation
• [x] Create repository
• [x] Create a README based on the standard abstract
• [x] Download the standard and move the content to GitHub.
• [x] Create managing team
• [x] Invite all relevant people to the team managing the standard on GitHub.
• [x] Describe migration in an issue
• [x] Create a release
• [x] Document URL redirect

[peterdesmet]

@tdwg/vocab is this "standard" related to the work at https://github.com/tdwg/vocab? Where should http://www.tdwg.org/standards/147/ be redirected to? Where should I move the content?

[baskaufs]

Yes, it is related. It was never ratified and never will be because the Vocab Task Group is going to write a new draft standard that will replace it. But I think that it would be reasonable to archive it within the https://github.com/tdwg/vocab repository, probably in its own subfolder or maybe a tag? If you put the document(s) there, I'll create a link to them from the repository README. You could also redirect there from http://www.tdwg.org/standards/147/ . Are you going to have an actual redirect to a GitHub page or will the existing page remain with a link to some GitHub landing page?

[baskaufs]

OK, I just checked and it looks like the "download" is just a single document. I'm not sure what the convention should be since this is kind of an edge case. There are a number of old or unfinished standards that aren't being actively maintained by a group, but this is probably the only one that is actively being re-written. Maybe the thing to do would be to create a subfolder within the Vocab repository that has some meaningful name related to the unfinished draft standard. The single document could be put there along with a readme that explains what's going on with the unfinished standard. I could link to that readme from the main Vocab readme and you could also redirect there from http://www.tdwg.org/standards/147/ . I don't think there is just one right way to do it, but I think this would probably work.

[baskaufs]

@tdwg/vocab I see that I should have probably "at mentioned" the vocab group in my previous comments on this issue, since they are related to the work of the group (vocabulary management).

I was trying to remember the extent to which the methods of archiving documents was an official part of the TDWG Process or whether there was actually no official process. I found a page on "Documentation within TDWG" [1] with the relevant section "What goes where?". Most of what's written in that section refers to non-functional parts of the TDWG website. However, "3. Standards Repository" reflects the concept that documents that form parts of formal standards need to be stored in the "standards repository", which I think is now de-facto the TDWG GitHub site.

A fuzzy part of what's written in that section of the page is "When a standard is proposed the documents are loaded into the repository where they are managed through the process of becoming ratified." Having suffered through the process of being a review manager, I'm aware that there are a number of places in the ratification process where documents that are created in different stages are supposed to be stashed away. The existing mechanism is the icky OJS system that is hard to use and unstable. Some of the documents that I was supposed to upload were confidential, e.g. anonymous review. Those obviously can't be put in the open on GitHub. But non-public documents from previous reviews do need to be saved somewhere. It is helpful for a new review manager to see what previous review managers have done and in the case where a new review manager has to take over for a previous one (as was the case for me) it is critical that the earlier documents in the review process be available to the new manager. So I'm not sure how documents related to the review process should be archived. There a lots of them in the OJS system and they shouldn't be lost if it's shut down. The review manager guidelines talk a lot about what needs to be saved at various steps in the process, but I can't remember where it is found on the TDWG website.

[1] http://www.tdwg.org/activities/documentation/

[peterdesmet]

In the future, these intermediate ratification steps are probably best supported as releases of the repository. See https://github.com/tdwg/dwc/releases for an example.

Regarding the download file: yes, having it as a subfolder is one option, but then it keeps lingering around. Another option is to:

1. Add it to a branch of the repo
2. Create a release from the branch (= zip)
3. Remove the branch, so it doesn't confuse anyone.
4. Link to the release from the README
5. Redirect the permanent URL to the current GitHub repo, not a specific version. From there, one can find the old version in the README. This is then in line with the other standards. Alternatively, we could redirect to the specific release.

Adding @mdoering, as he's also knowledgable about creating releases and keeping repos clean.

[baskaufs]

I think you should implement this as you think best. I'm not familiar enough with how to do all of these GitHub functions, so if you can just put the old standard within the vocab repo in a manner consistent with what you've done for other standards, that would be great. If I know where it ends up, I can write an explanation of what it is and link to it in the README

[peterdesmet]

Information has been migrated. Please review at: https://github.com/tdwg/vocab/issues/10.

I'll close this issue if all items on the task list are done.