NCEAS / eml

Ecological Metadata Language (EML)
https://eml.ecoinformatics.org/
GNU General Public License v2.0
41 stars 15 forks source link

final EML 2.2 documentation cleanup #340

Closed mbjones closed 5 years ago

mbjones commented 5 years ago
mobb commented 5 years ago

semantic primer TO DOs:

  1. add section numbers (letters?)

    • A. Introduction
    • B. Semantics annotations in EML 2.2
    • C. Appendix A reader should be able to create an EML annotation with examples, etc in section B alone (which currently is about half the total pages). Section C is for more in-depth info if they want it.
  2. It should also be obvious to readers that they will need to have some external vocabs recommended. We have not come out and said that anywhere. nor have we started on a list recommendations, except de facto (in examples). My current feeling is that we add our example onts to the glossary (or appendix sub-section titled "Vocabs in examples"), but save formal recommendations for a separate doc.

  3. enhance sub-section "organization of this doc" . describe A, B, C sections.

  4. In each example's intro paragraph, use a list to highlight the three parts of the semantic statement. move parentheticals about external vocabs to appendix

  5. introduce the "semantic statement" (plain english, no tech) right after the first code block showing an annotation node (on p2). link to below (addresses SC's comment).

  6. add these terms to glossary (or other appendix section), link in text as much as possible:

stevenchong commented 5 years ago

More semantic primer to do's:

mbjones commented 5 years ago

Updated release notes.

mbjones commented 5 years ago

Removed the validation service links from the docs. Much easier to run the validation class locally.

mbjones commented 5 years ago

Deprecated the eml-access module in the docs, discouraging use of the access elements. See sha 24301e3b94c29c2152d81553e5d6153d74629949.

mbjones commented 5 years ago

Updated README and contributors doc to remove language about the ecoinformatics charter, and instead just refer to maintainers for decisions. See sha 15999974.

mbjones commented 5 years ago

Added a codemeta.json file and a 'Copy Bibtex' button in sha 5f3fccd9.