[LTER-emlbestpractices] EML Best Practices doc, v 3 - release candidate

Wed Nov 1 10:39:13 PDT 2017

Hi all -
I am writing to LTER's "EML BP" list since this group produced version 2 of
the "EML BP doc", back in 2010. As you know, EDI is now managing this type
of resource for a wide community, which includes LTER. I am the one
organizing these materials for the EDI web site.

First of all, if you are no longer interested in this topic, feel free to
disregard this message. If you are still interested, thank you! You should
keep in mind that the general discussion about migrating portions of the
the LTER IMC website are taking place in LTER's "Wired" working group, and
you should contact them for general concerns.

Attached below is the "release candidate" for Version 3 of the EML BP doc.
By "release candidate", I mean that this doc will be posted publicly on the
EDI website if there are no major problems. Minor issues can be addressed
with patches. You should know that in the interest of speed, I have been
the only editor on V3.

-----
A few notes on the changes between V2 and V3:

A. General organzation
A.1. the most significant change to V3 was to remove its specificity to one
community, i.e., to LTER. But as LTER IMs (you) are without a doubt its
most important contributors, I added a section to the introduction about
the history, including contributors' names (based on WG participant lists).
Generally though, editing meant adjusting the language to not equate "EML
preparers" with "LTER sites". The examples have not changed, and all still
refer to data from the "Fictitious LTER Site, or FLS".

A.2. Some recommendations that are generally useful also have special
context. E.g., use of an XML element or attribute may be requested by a
community (e.g., LTER), or is even required by the EDI repository (but not
by other repositories). These were left in, because they highlight
important aspects of what has been learned in practice. But Instead of
integrating those with the general text, they are in highlighted paragraphs
as "Context notes".

A.3. V2 included a major section about EML for applications, like LTERMaps,
Metacat and PASTA. These were removed so that V3 is specific to EML content
only. The other material will be reviewed and housed with appropriate
projects, and cross-linked with EDI resources as appropriate.  V2 also
included some general info about EML design, eg., a description of the
attribute-unit model, and its use of XML types. These can become
stand-alone resources (web pages). I think keeping the V3 doc specific to
EML content will make its overall management easier, and creation of other
resources can be more flexible.

B. changes to the recommendations themselves...
..are few. I have highlighted them here, in case you want to pay special
attention to those sections. I think these generally reflect the way people
are using EML, which has changed some since 2010. If you disagree, please
start a discussion.

B.1. Since external ids (ORCIDs) are available for people, V3 says that
addresses can be omitted if an ORCID is present. V2 said that addresses
should be filled out.

B.2. spatialSamplingUnits: V2 recommended that this element (under the
methods tree) be used for individual sampling sites, and at the dataset
level, geographicCoverage was for general coverage. V3 says that individual
sites can go at the dataset level too, and the recommendation for
spatialSamplingUnits is a "context note" for LTER.

B.3. pubDate - Since this is used in citations, V3 has stronger language
that the pubDate should should reflect the data's "recentness".

B.4. We have seen code included as an otherEntity. So it is added to the
list of "typical uses" in the Entity section. I am ambivalent about whether
this really is "good practice".

C. Management
PDF format:
There has been discussion (and attempts) to make this document dynamic,
e.g., to split up and convert to HTML. However, there are technical
constraints that make examples, etc. problematic to display, and citation
is simpler if the doc is kept entire. There are other online best practice
resources (e.g., DataONE, and the EML project itself), and EDI is working
with those groups to see if this doc's recommendations can be integrated.
For the time being though, it will be distributed as a PDF doc.

GitHub:
the examples and doc itself are housed in a github repository
https://github.com/EDIorg/dm-best-practices
The repo is not fully populated today, but will have several additions over
the next week.

EML 2.2
This is in the works, and discussion is taking place on github:
https://github.com/NCEAS/eml/
Join in any time. We should probably think about EML-BP-V4, some time after
the EML 2.2 release.

-----
I think that's enough for now. I hope you have time to take a look at the
attached doc. There is a time constraint: EDI needs this doc for a workshop
the week of Nov 13, so if you have major comments, please make them before
then. Minor comments can certainly go into patches.

Comments in the word-doc itself are fine. If you would like to discuss,
slack is probably the most efficient, so I started a channel: #eml-bp at
edi-got-data.slack.com.

thanks again for your time -
Margaret

Margaret O'Brien
ORCID: 0000-0002-1693-8322
Information Management
Marine Science Institute, UCSB
Santa Barbara, CA 93106
805-893-2071 <(805)%20893-2071> (voice)
http://environmentaldatainitiative.org
http://sbc.marinebon.org
http://sbc.lternet.edu
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lternet.edu/pipermail/emlbestpractices/attachments/20171101/eedee1cd/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: emlbestpractices-v3.docx
Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Size: 116976 bytes
Desc: not available
URL: <http://lists.lternet.edu/pipermail/emlbestpractices/attachments/20171101/eedee1cd/attachment-0001.docx>