From c590d2e65cdf1abe95fbd2afdfe16e0bc77d78d0 Mon Sep 17 00:00:00 2001 From: Steve Baskauf Date: Wed, 29 Jan 2020 09:00:35 -0600 Subject: [PATCH] finish proofreading of release notes --- historical/release-notes-2020-01-27.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/historical/release-notes-2020-01-27.md b/historical/release-notes-2020-01-27.md index 898ece0..31990b3 100644 --- a/historical/release-notes-2020-01-27.md +++ b/historical/release-notes-2020-01-27.md @@ -6,7 +6,7 @@ ## Scope -The 2020-01-27 version of the [Audubon Core standard](https://www.tdwg.org/standards/ac/) updates two documents: the [Audubon Core Term List](https://tdwg.github.io/ac/termlist/) and [Audubon Core Structure](https://tdwg.github.io/ac/structure/), and the Audubon Core vocabulary itself. +The 2020-01-27 version of the [Audubon Core standard](https://www.tdwg.org/standards/ac/) updates the Audubon Core vocabulary and two documents: the [Audubon Core Term List](https://tdwg.github.io/ac/termlist/) and [Audubon Core Structure](https://tdwg.github.io/ac/structure/). ## Summary of changes @@ -24,7 +24,7 @@ These changes were [approved by the TDWG Executive Committee on 2019-12-01](http ### Minor changes to the vocabulary -A smaller number of changes were made to normative term definitions or usage guidelines. Those changes are summarized [here](https://github.com/tdwg/ac/blob/master/historical/minor-errata-definition-changes-2020-01-27-version.pdf). In an effort to maintain the stability of the vocabulary, these changes primarily affected the clarity of the metadata and not term meanings nor usage guidelines. Nevertheless, Audubon Core implementers should review these changes carefully to ensure conformance. +A smaller number of changes were made to normative term definitions or usage guidelines. Those changes are summarized [here](https://github.com/tdwg/ac/blob/master/historical/minor-errata-definition-changes-2020-01-27-version.pdf). In an effort to maintain the stability of the vocabulary, the changes primarily affected the clarity of the metadata and not term meanings nor usage guidelines. Nevertheless, Audubon Core implementers should review these changes carefully to ensure conformance with the standard. ### Additional clarifications and corrections to term metadata @@ -50,17 +50,17 @@ The sections above detail the specific changes that were made to the standard. H 1. The content was stored in ideosyncratic wiki syntax. -The end result was that it was difficult to change and track this vocabulary. That was particularly problematic given the complexities introduced by the large number of terms borrowed from other vocabularies. +The end result was that it was difficult to change and track the standard. That was particularly problematic given the complexities introduced by the large number of terms borrowed by Audubon Core from other vocabularies. When the Audubon Core Maintenance Group was established in 2018, it began implementation of new procedures designed to overcome the deficiencies listed above and streamline the process of implementing term changes and additions. ### Single point of entry for term metadata -Term additions and changes are made in a single spreadsheet that contains a line for every term whose metadata is being changed ([example](https://github.com/tdwg/rs.tdwg.org/blob/master/process/ac-revisions-2020-01-27/audubon-revisions.csv)). A [Python script](https://github.com/tdwg/rs.tdwg.org/blob/master/process/process_rs_tdwg_org.ipynb) is used to generate new versions of the terms and their containing term lists, vocabulary, and standard. It also adds machine-generated metadata such as modification dateTime. When the script is run in a branch of the [rs.tdwg.org repository](https://github.com/tdwg/rs.tdwg.org) the [diff](https://github.com/tdwg/rs.tdwg.org/pull/32/files) can be used to verify that only the intended changes have been made prior to merging the branch. After the merge, the authoritative machine-accessible CSV files in the rs.tdwg.org repository fully document the changes involved in the new version. +Term additions and changes are made in a single CSV table that contains a line for every term whose metadata is being changed ([example](https://github.com/tdwg/rs.tdwg.org/blob/master/process/ac-revisions-2020-01-27/audubon-revisions.csv)). A [Python script](https://github.com/tdwg/rs.tdwg.org/blob/master/process/process_rs_tdwg_org.ipynb) is used to generate new versions of the terms and their containing term lists, the vocabulary, and the standard. The script also adds machine-generated metadata such as modification dateTime. When the script is run in a branch of the [rs.tdwg.org repository](https://github.com/tdwg/rs.tdwg.org) the [diff](https://github.com/tdwg/rs.tdwg.org/pull/32/files) can be used to verify that only the intended changes have been made prior to merging the branch. After the merge, the authoritative machine-accessible CSV files in the rs.tdwg.org repository fully document the changes involved in the new version. ### Generation of the Term List document by build script -The [term metadata section](https://tdwg.github.io/ac/termlist/#7-vocabularies) of the Term List document is generated by a [build script](https://github.com/tdwg/ac/blob/master/code/build_page.py) using the data in the rs.tdwg.org CSV files. This ensures that there are no differences in term metadata between the machine-accessible metadata and the human readable documents that might be caused by manual editing. +The [term metadata section](https://tdwg.github.io/ac/termlist/#7-vocabularies) of the Term List document is generated by a [build script](https://github.com/tdwg/ac/blob/master/code/build_page.py) using the data in the rs.tdwg.org CSV files. This ensures that there are no differences in term metadata that might be caused by manual editing between the machine-accessible metadata and the human readable documents. ### Use of Markdown @@ -68,4 +68,4 @@ The Audubon Core documents are now written in Markdown, making it possible to ea ### Easy of maintenance -The changes described above will greatly simplify the process of maintaining the vocabulary and documents associated with Audubon Core, making it possible for the standard to evolve in response to the needs of the biodiversity informatics community in the future. +The changes described above has greatly simplified the process of maintaining the vocabulary and documents associated with Audubon Core, making it possible for the standard to evolve in response to the needs of the biodiversity informatics community in the future. It also enables robust tracking of the version history of the standard so that anyone can see how the standard has changed over time.