[NeXus-committee] comments on PDF manual

[Joachim Wuttke]

I am reading the compound PDF manual, release 3.1 of 2014-06-10.

I printed and bound the 360 pages, so that it feels like a serious
book. The first thing I then noticed is the absence of proper
front matter: copyright notice, document license, authors, year,
contact address with invitation to send feedback.

Lacking such information, I am sending my feedback to this list.

In Sect. 2.3.1 "NeXus Class Specifications", unnumbered
subsubsubsection "Overview of NeXus classes", first paragraph says:
"... is described in two basic ways: First, ..., then ..., then ..."
This makes three. Anyway, for easy readability, "first" should be
followed by "second", not by "then".

Two pages further on, there is a subsubsubsection "NeXus Class
Specifications", which repeats the header of the subsubsection.
It is immediately followed by the subsubsubsubsection header
"Base Clase Definitions". Which means that the core of the manual,
the definitions of the individual classes, resides in
subsubsubsubsubsections. I suggest to restructure this so
that the individual definitions are promoted to subsubsection
level, and listed in the table of contents.

Looking for a class definition in the index, it took me quite
a while to find it not under "NX..." but under "class definition".
I suggest to give up the two-level hierarchy of the index in
favor of a strictly alphabetical order. An index should primarily
support quick search. To expose the systematics of the manual,
it would be more appropriate to make the table of contents
more exhaustive, going down at least to subsubsection level.

Best - Joachim

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4916 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://lists.nexusformat.org/pipermail/nexus-committee/attachments/20140708/83be3537/attachment.p7s>