[ome-devel] Fwd: experience with OME

[josh.moore at gmx.de]

I can concur: Will's scripts rock! Unfortunately, I consistently
forget to show them to people, which is odd because one of the first
questions I get asked by almost any developer is: "where do I find out
more about the model?" When trying to work with the objects and write
queries, docs are critically important.

I typically send people here:

  http://hudson.openmicroscopy.org.uk/job/OMERO/javadoc/

or more specifically:

  http://hudson.openmicroscopy.org.uk/job/OMERO/javadoc/slice2html/omero/model.html        

but it's obvious: that's not enough! (by a long shot; nevertheless,
thanks to Andrew for making them much nicer to read.)

One helpful move would be to have all the documentation (for how to
work with the modely in XML, OMERO, ...) in the XSD so that everything
gets generated together.

On the other hand, I don't think we can get past having
simplifications like:

  http://www.ome-xml.org/wiki/ScreenPlateWell

for everything, really. Keeping them in sync is a huge task, though.

Cheers,
~Josh.


Will Moore writes:
 > Hi Curtis...
 > 
 > On 16 Sep 2009, at 23:09, Curtis Rueden wrote:
 > 
 > > We definitely want to encourage this sort of thing. My group (LOCI)  
 > > is in the middle of a similar effort, mapping all our acquisition  
 > > metadata to OME-XML, and working to produce valid OME-TIFF files in  
 > > every case.
 > >
 > > So yes, the documentation is supposed to help. I agree that the  
 > > documentation in the schema itself could use a lot of improvement.  
 > > My group has a graduate student in library sciences, Caitlin  
 > > Sticco, who is currently analyzing the schema and compiling a list  
 > > of suggestions and improvements; hopefully we can update the  
 > > documentation as well as we work to improve the schema.
 > >
 > > Caitlin and I are also discussing how to make better diagrams$,1rt(Bone  
 > > idea we had is to generate them in Graphviz format from the XSD  
 > > file. Any other suggestions for ways to make useful pictures would  
 > > be welcome.
 > 
 > I've been using a combination of xsl, javascript (jQuery) etc to turn  
 > the ome.xsd into a browsable hierarchy.
 > 
 > http://cvs.openmicroscopy.org.uk/snapshots/omero/editor/omeXsd/ome- 
 > r373.xsd
 > 
 > Handy because it's instantly updated if you're editing the xsd, and  
 > hierarchy is easy to understand.
 > 
 > Use links on the top to expand/collapse all or show/hide docs.
 > 
 > Obviously this code could be extended to do a bunch of other stuff.  
 > E.g. JM suggested allowing the root element to be chosen, e.g.  
 > "Image" or "Instrument".
 > 
 > 
 >    Will.
 > 
 > 
 > 
 > >
 > > Your idea of a list of common use cases, and how to express them in  
 > > OME-XML, is a great one. We should add that to the OME-XML web  
 > > site. For that, we need A) a list of which common use cases to  
 > > include; and B) someone with enough time to work on writing it up.  
 > > But at the least we can file a ticket about it on the OME-XML Trac  
 > > at http://www.ome-xml.org/. And actually, you are welcome to file  
 > > such tickets too, using the ome/ome login. :-)  To be clear, we  
 > > want to encourage external suggestions through that mechanism.
 >