Documentation Conventions/Standards
Chad Berkley
berkley at nceas.ucsb.edu
Mon Sep 16 13:55:55 PDT 2002
see my additions below:
On Mon, 2002-09-16 at 13:53, Scott Chapal wrote:
>
> 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...
This field should be a complete description. At least a paragraph
for the smaller fields, several paragraphs for the fields that need a
lot of description.
>
> 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.
If you know the lineage, fill it in. If not, leave it as it is.
>
> 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
>
> _______________________________________________
> eml-dev mailing list
> eml-dev at ecoinformatics.org
> http://www.ecoinformatics.org/mailman/listinfo/eml-dev
--
-----------------------
Chad Berkley
National Center for
Ecological Analysis
and Synthesis (NCEAS)
berkley at nceas.ucsb.edu
-----------------------
More information about the Eml-dev
mailing list