This is great to see a new approach on improving HDF5’s reference manual, and actually I still prefer the ancient pages such as https://support.hdfgroup.org/HDF5/doc/RM/RM_H5D.html#Dataset-Write over the newer ones such as https://portal.hdfgroup.org/display/HDF5/H5D_WRITE . One reason is that the old ones come up in google search for “H5Dwrite” right away, whereas the new ones are not found by it. The new ones require going through the HDF5 website to find it in the first place. Also it’s confusing in the new pages that the “procedure” is written in all uppercase, to it looks like Fortran documentation on first view, then only later follow the C details. All that is redundant information taking up unnecessary space, while the old version is right to the point of providing the actual information without gimmicks around it.
There are now two prominently competing examples on code documentation via the C++ documentation, such as en.cppreference.com versus www.cplusplus.com, both approaches providing different styles for same functions, e.g.:
I’m not even sure yet myself which of these styles I prefer. Both have their pros and cons. The one style is more minimalistic, allowing to focus, the other one more comprehensive, allowing easier navigation to similar functions.
For HDF5, I’d very much favor documentation to be autogenerated from the code such that both options are possible. Doxygen as documentation generator allows for multiple such styles via its configuration, thus there is no requirement to be limited to only one layout. I’d consider such direct integration with code better than manually written documentation in a wiki, but addon-pages such as describing examples can still be managed through some community-driven repository. Maybe a separate SVN or GIT repository that is pulled by an automated nightly build system for the HDF5 documentation?
On that aspect, I would disagree with the non-functional requirements as listed in https://hdf5.wiki/index.php/RM:Requirements#Non-Functional_Requirements ; not the “site” should be editable such that “Authenticated and authorized users shall have the ability to create new documents and modify existing documents”, but rather the sources that are used to automatically build that site should be editable and modifiable by authorized users - like a GIT repository for documentation addons that is pulled in addition to HDF5 main code to create and update the documentation side.
That way everyone can build the documentation on their own as well, use it offline, and also use different documentation styles, not being limited to the one particular layout as chosen by the main site. Building documentation rather than directly writing it bound to a specific style gives the same options like those two competing C++ documentation websites.