Initial Steps in Modernizing Boost.Graph Documentation
Hello Boost Graph community! We have taken the first step in modernizing the Boost.Graph documentation with a preview available here. These improvements aim to address frequent complaints from users collected during the 2022 User Survey and BGL workshop, including:
- Documentation hard to explore (no table of contents, no search bar)
- Examples using outdated C++, with some not even compiling
- Outdated visual design
We have invested in several dimensions:
- Migrating old pure HTML pages to Asciidoc + Antora
- Compiling and running modern examples for each algorithm in CI, with output integrated into the documentation
- Enhancing scanability for algorithm complexity and where defined
- Providing a better landing for users unfamiliar with property maps
The current PR is unmerged as we are assessing its viability. Important: this is NOT the final vision; it is intended as a first important step. The current scope is NOT a full rewrite/reorganization of each algorithm page, but a modernization of the documentation infrastructure. We are just worried we may have made important mistakes that should prevent the merge.
Questions to the Community:
- Is the new documentation preview going in the right direction?
- Is it better than the old documentation?
- Would you want to see it merged in its current state or have you identified important mistakes we should fix before merge?
Any general complaints not directly related to this PR scope are welcome and will be integrated into future work :) Thank you for your time.
Blogger's Review: The modernization of Boost.Graph documentation is an inevitable trend, particularly in enhancing user experience and accessibility. By incorporating modern technologies and tools, it effectively reduces the learning curve for users and enhances the practical utility of the documentation. However, community feedback is crucial before merging to ensure quality and accuracy. Developers should take user opinions seriously to ensure the final version gains broad acceptance.