Refactoring Jupyter Book 2 documentation ahead of a major release
Documentation is what turns open source code into products that people actually want to use. We recently spent a few days refactoring the Jupyter Book documentation to prepare for the upcoming Jupyter Book 2 release, and we’re excited about how much clearer the docs have become!
What we did #
We restructured the docs using the Diataxis framework to better organize content by user type and task:
- Reorganized into clear topic areas with landing pages for easier navigation
- Added missing content like the feature voting table and contributing guides
- Created upgrade guidance to help users understand the relationship between Jupyter Book 2 and MyST
This work helps users find what they need faster and gives the project a stronger foundation to build on going forward.
Why we’re excited about it #
Better documentation reduces maintainer burden by helping users answer their own questions, and it makes the project more welcoming and useful to new contributors. We hope this makes Jupyter Book more accessible to everyone and lays a good foundation for the new release!
We’re also excited because so many others helped provide edits and comments!
Learn more #
Acknowledgements #
- Thanks to @rlanzafame, @FreekPols, and @bsipocz for their helpful reviews, edits, and feedback on the PR!
- Project Pythia, CryoCloud, and the Berkeley educational projects are our primary member communities using MyST and Jupyter Book. Their support covers the cost of these kinds of foundational contributions.
Thanks for reading! If you'd like to follow our work, join our mailing list or subscribe to our blog. You can read our community hub documentation or learn about membership.
