search

tdwg / vocab

Vocabulary Maintenance Specification Task Group + SDS + VMS
11 stars 6 forks source link

Review migrated Standards Documentation Specification #10

Closed peterdesmet closed 9 years ago

peterdesmet commented 9 years ago

As discussed in this comment, we'll maintain an archived copy of the Standards Documentation Specification in this repository. I have just imported that information in this branch: https://github.com/tdwg/vocab/tree/sds. Please review (and edit) it before I create an archive (= release of it).

Note: Ignore the yellow banner on the repo homepage: do not create a pull request.

Once I have the go ahead from the @vocab team, I'll:

  1. Create a release
  2. Remove the sds branch so it doesn't confuse anyone
  3. Notify @baskaufs to reference the release in the README on master

In the near future, http://www.tdwg.org/standards/147/ will then redirect to https://github.com/tdwg/vocab, where users will be see the README and the link to the archived version.

baskaufs commented 9 years ago

@peterdesmet

  1. I think the README is OK, given that this is essentially a frozen version of what was originally posted on the TDWG website. The "Status" line clearly says that it is a draft standard, so no one should be confused about that. If the landing page for the redirect is the vocab group home page, then the current status of the draft (i.e. abandoned with a new standard under construction) will be clear to anyone who follows the permanent URL.
  2. Yes, having the file as a Word document is a violation of the rules set out in the file, which says that standards documents should be in an open format. PDF is listed as acceptable, DOC is not. In the past, I made a pdf of the document - it's at http://bioimages.vanderbilt.edu/pages/tdwg-stds-spec.pdf if you want to retrieve it or you can generate a PDF yourself. In the spirit of keeping stuff in the form it was submitted, maybe both the PDF and Word documents should be there.
  3. I suppose including a preferred citation would be good, but I'm not sure what it should be. Maybe something like:

Hyam, Roger. 2007. TDWG Standards Documentation Specification (draft standard). TDWG Infrastructure Project. 2007-11-05 version. http://www.tdwg.org/standards/147/

Is there a convention on the format already from the other standards, e.g. AC and DwC?

peterdesmet commented 9 years ago

I've uploaded the pdf file you referenced. The download link now states:

Download: Original download (Microsoft Word document) / PDF version

I'm waiting on https://github.com/tdwg/infrastructure/issues/32 to add the preferred citation.

peterdesmet commented 9 years ago

https://github.com/tdwg/vocab/commit/b5b9ef5d17bf1f50fcfea37a692de6f4345ee428: Similar to https://github.com/tdwg/abcddna, I've decided not to keep the doc around. I find it more confusing that there are 2 files, than just a single, readable one. I gave it the name of the original file: 147-483-4-RV.pdf. What's left to do now, is the preferred citation.

baskaufs commented 9 years ago

See https://github.com/tdwg/infrastructure/issues/32 for discussion on preferred citation

peterdesmet commented 9 years ago

Following the discussion on a standard preferred citation, this is what I added to this repo:

Vocabulary Maintenance Specification task group. 2015. Vocabulary Maintenance Specification (VOCAB), Version 0.1. Biodiversity Information Standards (TDWG) http://www.tdwg.org/standards/147

It's probably incorrect (I had to invent a version + used the task group as the author). Please update and let me know.

peterdesmet commented 9 years ago

I got a bit confused, and added this to the master branch. I have now added this to the sds branch as well:

peterdesmet commented 9 years ago

To summarize and review:

Master branch

Vocabulary Maintenance Specification task group. 2015. Vocabulary Maintenance Specification (VOCAB), Version 0.1. Biodiversity Information Standards (TDWG) http://www.tdwg.org/standards/147

SDS archived branch

TDWG Infrastructure project. 2007. TDWG Standards Documentation Specification (SDS), Version 2007-02-06. Biodiversity Information Standards (TDWG) http://www.tdwg.org/standards/147

baskaufs commented 9 years ago

Two comments: -it might be good to include the word "draft" somewhere in the SDS title, although I suppose readers could discover that by clicking on the permanent URL link.

peterdesmet commented 9 years ago

Updated preferred citation for archived branch to:

TDWG Infrastructure project. 2007. TDWG Standards Documentation Specification (SDS), Draft version 2007-02-06. Biodiversity Information Standards (TDWG) http://www.tdwg.org/standards/147

I will create a release of this branch.

peterdesmet commented 9 years ago

Now released: https://github.com/tdwg/vocab/releases/tag/2007-02-06-sds Let me know if you have remarks regarding the release description. I've deleted the sds branch to avoid confusion (all content is in the release anyway).