Launching Jupyter Book for 2i2c Communities
A core component of our mission to make research and education more impactful, accessible, and delightful is leveraging our unique global network of communities to make meaningful improvements to the open-source tools that power their work. Learning from one community can then provide value to our entire network, e.g., our work with PACE on speeding up their CNN model training.
Central to our communities’ work is the importance of sharing new findings, best practices, and community resources. Across our network, we have seen communities creating their own “books” that provide a home for this kind of content. Many of these books feature the concept of a “landing page” that welcomes new members, establishes an identity, and provides jumping-off points (or “calls to action”) to more detailed resources.
Until now, each community has been required to undertake this work independently. 2i2c believes that by building upon existing open-source tools like Jupyter Book 2, we can help communities focus on the content of their home, rather than spending time worrying about its appearance. To that end, we have been working on an initiative to allow communities to rapidly build interactive starter documentation and provide users with a rich, interactive, and informative onboarding experience. Through this initiative, we have:
- Improved the user experience of launching into interactive compute environments from a Jupyter Book.
- Built components into the Jupyter Book “book theme” for low-density landing page content like call-to-action blocks.
- Extended our service to co-locate community documentation alongside community hubs (i.e.,
docs.hub.2i2c.cloud).
To take advantage of this feature, communities can use the
2i2c-org/community-docs-template to deploy a Jupyter Book site to GitHub Pages. This template demonstrates simple usage of Jupyter Book 2 for computational content and landing page creation, and establishes the necessary CD workflows for web publication. Meanwhile, 2i2c can update our domain name management to point the docs.hub.2i2c.cloud nested subdomain to the newly deployed documentation.
For more information, see our community documentation for deploying Jupyter Books.
Developing these new capabilities taught us a lot about what makes building “good” community documentation so difficult. A wide range of bespoke website-building tools and integration quirks previously made it challenging for communities to both keep documentation current with internal changes and keep up with necessary software updates. We also learned that by trading bespoke complexity for simplicity and readability, we could build a solution that scales to multiple communities, with a consequently reduced maintenance burden.
With these improvements, we have initiated a conversation about what a more unified “look and feel” for our network might entail, and how it might benefit our communities. Much more can be done to build on this first step, and we are eager to gather feedback on how to improve these features for users.
To learn more about this work, consider exploring a minimal example on our Showcase Hub, and check out our service guide. Let us know what you think!
