We believe that the definition of quality of the HDF software includes the quality of its technical documentation. The three essential quality attributes of ease of use, ease of understanding, and ease of findability are not met by its current incarnation. We know it, you know it, and here’s what we’ll do about it: One of our supporters kindly agreed to fund a Productivity and Sustainability Improvement Planning project to create better end-user documentation for the HDF5 library, focusing on the Reference Manual (RM).
The current state of the RM might be described as Multiple RM versions based on different technologies exist. Stakeholders and requirements are not documented and partially unknown. The first step out of this peculiar situation will bring us to a state where Stakeholders and requirements are identified and recorded, and requirements prioritized. To make this step, we need your help and involvement.
To facilitate this process, we have created a “playground” where WE (including you!) can explore ideas and approaches to technical documentation. We’ve set up a MediaWiki installation. Does this mean that the next generation of HDF5 documentation will be based on this technology? Not necessarily. That’s why we want to hear from you, and the discussion is just getting underway, e.g., here.
While this effort is focused on the RM, we cannot ignore that the RM is only a small portion of the HDF5 documentation. Our long-term goal must be to find a technical solution that can accommodate all forms of HDF5 documentation.
If you are passionate about high-quality technical documentation, we want you to participate! You can start a documentation topic-related thread in the HDF forum, or if you have registered with us before, you can begin editing the HDF5 Wiki using your Auth0 credentials to sign-in.
Let’s get to work!
The HDF Group Documentation Committee
Gerd Heber (@gheber), Elena Pourmal (@epourmal), Binh-Minh Ribler (@bmribler), Barbara Jones (@bljones), and Lori Cooper (@lori.cooper)