documentation question.

[Christopher Jones]

Peter,

 > 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"?
 >
Yeah, some standardization in the lineage would be helpful.  I think it 
has just been evolving, and one of the goals is to record the 
standards-document where the element originated (i.e FGDC-STD-001-1998), 
but as a was working away on renaming elements in coverage, I realized 
that putting a path in that indicates *which* element from which the new 
element was derived will be extremely helpful when we sit down to right 
XSL to convert from one standard to the next.  Because it's a 
collaborative set of files, it's hard to keep track.

So, I'd suggest we do that whenever possible, potentially even using 
XPath type syntax, even though it would still be quite qualitative.  I 
tried doing that in eml-coverage.xsd.

> 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. 

I like the "introduced" syntax if it was truly an elemnt/idea unique to 
EML, but would provide lineage if possible/applicable.

> 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?

This is tough, because of the terse definitions in those standards. 
However, I've spent quite a bit of time documenting the *intent* of 
elements over and above the description from which they were derived. 
And yes, it's a pain in the ass.  However, for the documentation to 
truly be integrated into apps, I think it's needed.  Also, I think the 
*tone* of the documentation should be consistent and oriented toward the 
right audience.  I've struggled with this.  Some comments are needed for 
app developers, some for end users.  I was shooting for 
<xs:documentation> elements for developers, and <xs:appinfo> for 
generation into UIs for end users.

My 2% of a dollar,

Chris

-- 
_________________________________________________________________
christopher jones     cjones at lifesci.ucsb.edu      (805) 893-5144
marine science institute  university of california, santa barbara
_________________________________________________________________