[NeXus-definitions-tickets] [NeXusDefinitions] #86: review NeXus manual draft

[NeXus Base Classes and Instrument Definitions]

#86: review NeXus manual draft
------------------------+---------------------------------------------------
Reporter:  Pete Jemian  |      Owner:  Pete Jemian
    Type:  task         |     Status:  new        
Priority:  major        |   Keywords:             
------------------------+---------------------------------------------------

Comment(by Pete Jemian):

 = comments posted by an independent reviewer of the NeXus documentation =

 [edit: finally, I arrived at the section "NeXus: the basics for the truly
 impatient" which was actually what I was looking for. I guess this makes
 many of my comments below irrelevant; I'll send them anyway as I have
 written them down already.]

  * I did not get that the wiki version is actually outdated
  * The manual is indeed very long. I have the feeling that much text could
 be spared when more examples were given. Personally, I like very much
 http://diveintopython.org/toc/index.html which contains basically only
 examples.
  * More real-world examples would be useful. E.g. a file from a triple-
 axis spectrometer (one point detector scanning some angle) or FOCUS, a
 neutron time-of-flight spectrometer.
  * When describing the classes, it seems to me that there is the same
 information twice: once as xml text and once as table. One of them should
 be enough.
  * [minor] The xml descriptions have some typos, repeated words etc
  * It becomes not clear which entries are required and which are optional.
  * Make the "what is NeXus" more clear; I had always the impression that
 NeXus is a set of subroutines AND a set of design principles AND ... --
 and that I would need to follow all of them. Make more clear that these
 items are completely independent of each other. That I can write a NeXus
 file without using the subroutines, for example.
  * In fact, the verysimple.xml looks different from what Mark Koennecke
 has sent me as a FOCUS file. Is there no standard or is the example
 outdated? Or is Marks FOCUS file outdated?
  * You say that several file formats are available, namely HDF4/5 and XML.
 That sounds again as if I could write NeXus only in these file formats.
 However, It is only /the subroutines/ which are limited to these file
 formats.
  * Talk about old ways of doing something in footnotes only (if at all)
  * How the NXDL relates to NeXus is still unclear to me

-- 
Ticket URL: <http://trac.nexusformat.org/definitions/ticket/86#comment:5>
NeXus Base Classes and Instrument Definitions <http://www.nexusformat.org/>
NeXus Base Classes and Instrument Definitions