documentation question.

[Matt Jones]

Hi Peter,

Good points.  Those are all things that currently bug me about the 
documentation too.  My comments are inline:

Peter McCartney wrote:
> I have some questions about filling in eml-documentation since im not 
> sure im interpreting things right and eml-documentation.xsd is not, 
> ummm, documented :)
> 
> 1) lineage. My expectation was that this was an identification of the 
> original source of an element. As im reading through other people's 
> documentation entries, it seems to be used more for a record of what 
> version of EML an element first appears in. I filled the lineage field 
> for spatialReference as "FGDC-STD-001-1998" since each element was taken 
> from that source and i did not change any element names. is the point to 
> document the source definition or just its history vis a vis EML? 
> however, what if i use an element from an existing standard but modify 
> it somewhat (drop or add elements from its content model, but leave a 
> substantial amount of the content intact? should we have a standard 
> format such as "EML 2.0, modified from ISO 19115.3 A.2.3.4"?
> 

This was intended to help people do crosswalks to other standards by 
giving the standards from which it was taken.  I'm not sure what to do 
here.  As it stands now it isn't very useful.  I like your proposal for 
"EML 2.0.0, modified from ...".  This is something we could probably fix 
after the beta9 release (ie, it is somewhat lower priority to me). Do 
you agree?

> 2) it seems like we could trim some verbage and standardize some of the 
> entries. I'm not sure <lineage>New in EML 2.0</lineage> tells me 
> anything more than <lineage>EML 2.0</lineage>. When this appears in EML 
> 4.0 will we still say "New in EML 2.0" or will we change it to "Was 
> introduced in EML 2.0"  as i see being done for some elements from EML 
> 1.x ?.  in a similar manner, it seems like we could standardize on what 
> we put in the Example element (if anything) for complex elements and 
> elements based on complex types rather than a wordy phrase like "See 
> content models for associated elements" or something like that. 

agreed.  both the lineage and examples should be standardized.  For 
examples, if the element is a leaf node, it is nice to see some example 
text values.  Should we include the tags in a CDATA section?  I think 
not, because this is intended as end-user documentation.  For elements 
that are not leaf nodes, we won't have an text children directly, so the 
only example is to show a nested set of elements leading to the text in 
the leaf nodes.  I think this may be unneccesary for end users (who 
shouldn't be exposed to the markup anyway.  Maybe we should only provide 
examples for repeating elements. Either a single value ("fred"), or a 
list of comma separated values ("fred, barney, wilma"). Again, this is 
something we might do after beta9.

> 3) is it necessary to have a definition for every element? for most of 
> the elements from ISO and fgdc, all that was provided was a short phrase 
> that seems to fit best in summary. if our only choice is to repeate that 
> in description or leave description blank, which is better?
> 

Yes, a definition is required for every element.  We have recognized 
that there is a lot of redundancy, so we have come up with a scheme to 
reduce that (see 
http://bugzilla.ecoinformatics.org/show_bug.cgi?id=501), but have 
decided to wait on implementing it because it requires reorganizing all 
of the documentation.  So, basically, there would be some documentation 
restructuring to do for the release candidate, but we're hoping that the 
content models will be stable from beta9 and on.  Would you prefer to 
make the changes to documentation structure now? Do you think the 
proposal in bug 501 would help?  It would make the simplest 
documentation (in case we only have one sentence) be something like this:

<description><summary>The <tooltip>title field</tooltip> provides a full 
description of the resource.</summary></description>

Further elaboration could follow the summary element if it were available.

Thanks again,
Matt

-- 
*******************************************************************
Matt Jones                                    jones at nceas.ucsb.edu
http://www.nceas.ucsb.edu/    Fax: 425-920-2439   Ph: 907-789-0496
National Center for Ecological Analysis and Synthesis (NCEAS)

Interested in ecological informatics? http://www.ecoinformatics.org
*******************************************************************