documentation question.

[Peter McCartney]

Ok. sounds like im not out in left field on this one. i defintely agree this
is lower priority for beta 9 - i was just trying to avoid doing a bunch of
stuff wrong up front. 
Perhaps we need a concordance element in addition to lineage, but unless it
can be done in a way that would automatically generate our xslts for us, its
probably going to be  a lot of work for very little gain. 

thanks. 


Peter McCartney (peter.mccartney at asu.edu)
Center for Environmental Studies
Arizona State University
480-965-6791 

-----Original Message-----
From: Christopher Jones [mailto:cjones at lifesci.ucsb.edu]
Sent: Wednesday, May 22, 2002 3:41 PM
To: Peter McCartney
Cc: Eml-Dev (E-mail)
Subject: Re: documentation question.


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
_________________________________________________________________
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mercury.nceas.ucsb.edu/ecoinformatics/pipermail/eml-dev/attachments/20020522/a6da4bdb/attachment.htm