Documentation review - discussions

[hgoerzig]

Review existing documentation considering understandability for newbies. Related to issue: nexusformat/definitions#886

[BalazsBago]

Dear Heike,

This is what I have so far:

https://manual.nexusformat.org/introduction.html
Explanation of “Links” uses constructs (NXdata, NXmonitor…) which are undefined at this point of the documentation. The definitions in the design chapter (https://manual.nexusformat.org/design.html#nexus-objects-and-terms) seem clearer than these definitions in the introduction.

https://manual.nexusformat.org/design.html
The explanations are missing for the “data type” (NX_NUMBER, NX_FLOAT, etc …) in parentheses at fields and attributes.

https://manual.nexusformat.org/applying-nexus.html
It would be nice to have some suggestions to tools to create NeXus files (i.e.: NeXpy)

Do We have some strategy for partitioning the documentation, or all of us are going to read the whole documentation?

Cheers,
Balazs

[BalazsBago]

I have created issues for my remarks:

• Improve definitions in introduction definitions#1110
• Add explanation for data types definitions#1111
• Tool suggestion in the tutorial #87

[prjemian]

Individual issues are created so this issue is done. @hgoerzig @BalazsBago Thanks!