EML 2.0 release & Documentation Review

[Matt Jones]

eml-dev'ers,

The documentation takes a lot of work -- very few people have invested 
much time in it so far (Chad, Chris, and I have done the most), so it is 
very worthwhile to get some additional eyes critically reviewing it and 
updating it.  Thanks for your and Scott's contributions here -- they are 
appreciated.

Let's assume documentation can't be done by tomorrow, but we need to 
keep the pressure on to get it done ASAP.  This release has been forever 
in coming -- lets get it done.

The schemes are changing, but in fairly minor ways, and only for things 
that were decided earlier in discussions or in existing bugs.  Nothing 
out of the blue is happening.  The only remaining schema changes that I 
know of are described in bug 586 (key validation problems) and 484 
(changing unit and attributeDomain, and adding more standard units). 
These shouldn't really impact the documentation effort, and Chad and I 
will be sure to fully document any new schema changes that happen for 
those bugs, so you won't have to revisit those sections. The rest of the 
bugs are documentation bugs (567, 471, 495) or release preparation tasks 
that can't be done until the last minute (584).

As for your three issues:

David Blankman wrote:
> There are three separate but related issues that need to be addressed:
> 
>    1. What approach should be taken with the FGDC derived documentation?

It needs to be fixed, but it should be the lowest priority because there 
is a whole standards document backing it up.

>    2. Should we make a conceptual separation between the documentation
>       that is embedded in the schemas and user documentation? If we did
>       this then the documentation review could be speeded up since all
>       we would have to do is make sure that it is accurate rather than
>       easy to understand. (The people who have done the development
>       already understand what things mean and have difficulty judging
>       whether something is or is not understandable. Even I am may be
>       too close).

Yes.  The documentation in the schemas is to document EML itself. 
Applications that help people create EML are going to have to go a lot 
further than field definitions to help users create reasonable EML.  For 
now I guess I would worry mostly about making sure the docs are 
technicall correct, complete, and reasonably readable so that 
application developers can use the specification.  End-user 
documentation is a different ball of wax.

>    3. When should the Release Candidate be posted?
>       It seems to me that we have two options:
> 
> a.        post the release candidate with the disclaimer that the 
> documentation is not complete.
> 
> b.       delay the release until the documentation is complete.
> 

I vote for soon.  I see two the same two options as you:

a) We can post a release with incomplete docs (RC1) and say that the 
docs will be improved between RC1 and 2.0.0, but we might be better off 
with an RC2 if we do that. If we do a release now, it will at least 
allow others outside of our group to more easily look at what we have. 
There have been a lot of changes since beta9 for people to digest.  We 
might even call the current release "2.0.0beta10" if you're more 
comfortable with that.

b) We could delay the RC1 release by a week (target next Friday Sep 20), 
and try to have all of the doc changes done by Wednesday. I will not be 
able to contribute after tomorrow as I am completely swamped with 
traveling, so it would devolve to someone else to get the release ready 
to go (chad?).  There's a lot of last minute details to handle for the 
release after the schemas are completed. I'm worried that this week 
delay will easily turn into a month, and I don't want to see that.

So, given the options, I would vote for (a), release RC1 now, with the 
possibility of an RC2 if its deemed necessary when the docs are fully 
completed.  But we should still try to get as much of the doc work done 
now as possible.

Cheers,
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
*******************************************************************