# Ways to document how we save data to an HDF5 file **URL:** \ **Category:** HDF5 Library\ **Created:** [February 7, 2024, 11:09pm UTC](https://forum.hdfgroup.org/t/ways-to-document-how-we-save-data-to-an-hdf5-file/12005 "2024-02-07T23:09:47Z")\ **Posts on this page:** 7\ **Page:** 1
**Author:** ![mike.jackson](https://forum.hdfgroup.org/user_avatar/forum.hdfgroup.org/mike.jackson/32/1734_2.png) [@mike.jackson](https://forum.hdfgroup.org/u/mike.jackson)\ **Post date:** [February 7, 2024, 11:09pm UTC](https://forum.hdfgroup.org/t/ways-to-document-how-we-save-data-to-an-hdf5-file/12005/1 "2024-02-07T23:09:47Z")
Has anyone come up with a documentation method to document how their project stores data into an HDF5 file. - What format (Markdown, Restructured Text, HTML, other? ) - Do you use tables, hierarchical lists, outlines? Essentially I am trying to document things like: - This group will be named “foo” and have 3 attributes of types {String, Int, float} with values of {“Hello”, 10, 3.14159}. The group can have 2 data sets, those have names “Bar” and “Baz” and have … Things like that. With the ultimate goal of the final rendered documentation being actually easy to read and understand. If anyone has any examlpes that they have seen for the layout of this kind of documentation I sure would appreciate it. Thanks Mike Jackson ---
**Author:** ![brtnfld](https://forum.hdfgroup.org/user_avatar/forum.hdfgroup.org/brtnfld/32/1444_2.png) [@brtnfld](https://forum.hdfgroup.org/u/brtnfld)\ **Post date:** [February 13, 2024, 6:00pm UTC](https://forum.hdfgroup.org/t/ways-to-document-how-we-save-data-to-an-hdf5-file/12005/2 "2024-02-13T18:00:47Z")
XDMF, [https://www.xdmf.org](https://www.xdmf.org), is an example that uses text files (XML) to describe the data. XML might not be the best for easier documentation inclusion than the ones you mentioned, but some projects convert XML to markdown, for example. ---
**Author:** ![gheber](https://forum.hdfgroup.org/user_avatar/forum.hdfgroup.org/gheber/32/1919_2.png) [@gheber](https://forum.hdfgroup.org/u/gheber)\ **Post date:** [February 13, 2024, 11:26pm UTC](https://forum.hdfgroup.org/t/ways-to-document-how-we-save-data-to-an-hdf5-file/12005/3 "2024-02-13T23:26:09Z")
Maybe [HDF5/JSON](https://hdf5-json.readthedocs.io/en/latest/). See also the section on [JSON schema](https://hdf5-json.readthedocs.io/en/latest/schema/index.html). G. ---
**Author:** ![ajelenak](https://forum.hdfgroup.org/letter_avatar_proxy/v4/letter/a/3d9bf3/32.png) [@ajelenak](https://forum.hdfgroup.org/u/ajelenak)\ **Post date:** [February 14, 2024, 5:09pm UTC](https://forum.hdfgroup.org/t/ways-to-document-how-we-save-data-to-an-hdf5-file/12005/4 "2024-02-14T17:09:04Z")
One issue with HDF5/JSON for this task is that all HDF5 groups and datasets are represented flat which is not something users expect for a hierarchical data format. I tried to address this by proposing a YAML-based approach, described [here](https://ajelenak.github.io/ndl/). This was my little pet project, nothing official, and I did not do anything beyond a draft spec and several examples. A related question is whether it is better for users to describe content in terms of domain-specific objects that happen to be encoded in HDF5, rather than having to do this encoding themselves and write it out at the HDF5 level of detail. -Aleksandar ---
**Author:** ![gheber](https://forum.hdfgroup.org/user_avatar/forum.hdfgroup.org/gheber/32/1919_2.png) [@gheber](https://forum.hdfgroup.org/u/gheber)\ **Post date:** [February 15, 2024, 1:57pm UTC](https://forum.hdfgroup.org/t/ways-to-document-how-we-save-data-to-an-hdf5-file/12005/5 "2024-02-15T13:57:45Z")
Yup, it’s all about the audience. I like the approach taken by [h5RDMtoolbox](https://preprints.inggrid.org/repository/view/23/). G. ---
**Author:** ![ajelenak](https://forum.hdfgroup.org/letter_avatar_proxy/v4/letter/a/3d9bf3/32.png) [@ajelenak](https://forum.hdfgroup.org/u/ajelenak)\ **Post date:** [February 16, 2024, 3:43pm UTC](https://forum.hdfgroup.org/t/ways-to-document-how-we-save-data-to-an-hdf5-file/12005/6 "2024-02-16T15:43:19Z")
I’ve personally heard same question asked many times so some kind of a solution seems to be long overdue. Is there (finally) enough interest in the wider HDF community to tackle it and develop something? This is going to be the topic of my [Call the Doctor session next Tuesday](https://forum.hdfgroup.org/t/documenting-how-to-save-data-to-an-hdf5-files-aleksandar-jelenak-on-call-the-doctor-february-20-2024/12027). -Aleksandar ---
**Author:** ![mike.jackson](https://forum.hdfgroup.org/user_avatar/forum.hdfgroup.org/mike.jackson/32/1734_2.png) [@mike.jackson](https://forum.hdfgroup.org/u/mike.jackson)\ **Post date:** [February 16, 2024, 6:43pm UTC](https://forum.hdfgroup.org/t/ways-to-document-how-we-save-data-to-an-hdf5-file/12005/7 "2024-02-16T18:43:19Z")
I took a very quick look at that project and they do seem to preset the information in a good way. I also am looking at [https://github.com/oinanoanalysis/h5oina/blob/master/H5OINAFile.md](https://github.com/oinanoanalysis/h5oina/blob/master/H5OINAFile.md) as an example. We would like to essentially have someone who does not run our software be able to read the doc and understand where to find their data in the hdf5 file. If someone really wants to write an HDF5 file that conforms to our spec it could be used for that also.