Documentation Conventions/Standards

[Scott Chapal]

Documentation Reviewers:

As a preliminary follow-up to David's request, I would like to propose
some conventions/standards for content in documentation tags in the
schema.

All of these ideas are preliminary - please review them and comment
back to the list.  Hopefully we can converge on a list of conventions
to use quickly.

1) description tag

   When referring to a field for the first time use language like:
   The foo field is a ...

   NOT
   The foo element is a ...  
   OR
   The "foo" field is a ... 

   Subsequent references tp the field could be generic eg.:
   This field...

2) example tag

   If an example tag is not needed for whatever reason, don't leave
   empty example tags <doc:example /> in the element definition.

3) lineage tag

   The lineage tags are not used consistently.  They are not being
   rendered by the current version of the stylesheet.  They are being
   retained for the time being, but are not being updated as a goal
   for RC2.  Just leave them as-is for now.

4) tooltip tag

   These should be short and to-the-point.  Potential use might be for
   quick recognition of the Element in a mouse-over operation.

5) moduleDescription

   Might be enhanced by the work Chris is doing for the spec - he is
   thinking about moving the descriptive information into the schema.

6) recommendedUsage

   Short, descriptive - but use a complete sentence and correct grammar.

-Scott

David Blankman <dblankman at lternet.edu> writes:

> EML Release Candidate 1 will be posted on knb.ecoinformatics.org by
> the end of today.
> 
> 
> This release still has some unreviewed documentation. We need to have
> all eml-modules reviewed by Thrsday, September 19 in order to have EML
> Relase Candidate 2 posted on Friday, September 20.
> 
> 
> Keep in mind that this is technical documentation, not end user
> documentation. The target audience for this documentation is
> developers or people like the LTER information managers not ecology
> domain scientists.
> 
> 
> We need three kinds of help.
> 
> 1. Taking responsibility for the review of a specific module.
> In order to do this you should have both content expertise or, at
> least, content familiarity and eml/xml expertise. Some of the
> exisiting documentation has references to modules that are no longer
> part of EML, so to be responsible you have to have spent enough time
> with EML to be able to catch  references to incorrect
> terms. Realistically the pool of people who fill these criteria are
> probably people from NCEAS, CAP, NET, Scott Chapel, and probably Tim
> Bergsma and Ken Ramsey. In addition, a person should not be
> responsible for reviewing documentation that s/he has written.
> 
> 
> 2. GIS related module documentation
> . The documentation of modules have been recently added to EML and
> adapted from FGDC (spatialRaster, spatialVector, spatialReference) are
> by everyone's comments sparse and opaque. Anyone who is a GIS expert
> is encouraged to help in this documentation. If you are a GIS expert
> and would like to participate, please email David Blankman
> (dblankman at lternet.edu). I am assembling a team of GIS experts to help
> in this process. Once I hear back from people, we can figure out how
> to divide this up so that the documentation review can proceed
> efficiently and effectively.
> 
> 
> 3. General Content Review
> Anyone with content expertise, or at least content familiarity, is
> encouraged to review modules for both accuracy and readability.
> 
> 
> Responsibility Matrix:
> 
> ASSIGNED MODULES                PERSON RESPONSIBLE
> eml-access                            Scott Chapel
> (scott.chapel at jonesctr.org)              eml-attribute
> David Blankman (dblankman at lternet.edu)
> 
> eml-constraint                        Scott Chapel
> eml-dataTable                        David Blankman
> eml-entity                              David Blankman
> eml                                       NCEAS
> 
> UNASSIGNED MODULES
> 
> eml-coverage
> eml-dataset
> eml-literature
> eml-party
> eml-physical
> eml-project
> eml-protocol
> eml-resource
> eml-software
> eml-storedProcedure (post eml-beta8 addition)
> eml-view (post eml-beta8 addition)
>  GIS RELATED MODULES (Please email David Blankman if you have GIS
>  expertise and want to participate.)
> 
> eml-spatialRaster
> eml-spatialReference
> eml-spatialVector
> 
> People in the "Responsible pool", please list in order your preference
> the modules for which you want to be responsible. As soon as I have
> heard from a critical mass of people, I will resend the responsibility
> matrix.
> 
> 
> People who want to do general content review, please send your
> comments to the person who is responsible for a given module's
> documentation review.
> 
> 
> Thank you all in advance for whatever level of participation you choose.
> 
> 
> 
> --
> 
> David E. Blankman
> Database Integration Developer
> Long Term Ecological Research Network Office
> University of New Mexico
> 801 University, SE #104
> Albuquerque, NM 87106
> (505) 272-7346 / (505) 272-7080 FAX
> 

-- 
Scott E. Chapal_________________________________________________
Database & Network Manager             scott.chapal at jonesctr.org
J.W. Jones Ecological Research Center          229.734.4706 x227
Rt. 2. Box. 2324. Newton, GA 31770-9651        229.734.6650 :FAX