search

nexusformat / NIAC

Issue for the NIAC to discuss (no code)
2 stars 0 forks source link

Documentation review - discussions #83

Closed hgoerzig closed 2 years ago

hgoerzig commented 3 years ago

Review existing documentation considering understandability for newbies. Related to issue: https://github.com/nexusformat/definitions/issues/886

BalazsBago commented 3 years ago

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 commented 3 years ago

I have created issues for my remarks:

prjemian commented 2 years ago

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