Streamline JupyterBook Docs: Moving And Simplifying URLs

This article discusses the proposal to move live documentation to jupyterbook.org/docs/ and simplify the versioning URL structure for JupyterBook. This change aims to improve user experience by making documentation more accessible and easier to navigate. We will explore the context behind this proposal, the suggested changes, and the considerations that have been taken into account.

Context: Current Documentation Hosting and the Need for Versioning

Currently, JupyterBook's documentation is hosted directly at jupyterbook.org. While this approach has served its purpose, the need for versioned documentation has become increasingly apparent. Versioning allows users to access documentation specific to the version of JupyterBook they are using, ensuring they have the most accurate and relevant information. This is especially crucial for a project that is actively developed and evolving, as new features and changes are introduced regularly.

The proposal suggests moving to Read the Docs (RTD) to leverage its robust versioning capabilities. RTD is a popular platform for hosting documentation, offering features like automated builds, version management, and search functionality. However, the default RTD structure introduces language and version slugs in the URL (e.g., jupyterbook.org/en/latest/), which can make URLs unnecessarily complex and less user-friendly. This complexity can hinder users' ability to easily access and share specific documentation pages. To address this, a simplified URL structure is proposed to maintain a clean and intuitive user experience.

Why is Versioning Important?

Versioning is crucial for maintaining the integrity and usability of documentation. As software evolves, features are added, modified, or removed. Documentation that doesn't reflect these changes can lead to confusion and frustration for users. By providing versioned documentation, users can be confident that they are accessing information that is relevant to their specific version of JupyterBook. This ensures a smoother experience and reduces the likelihood of encountering issues due to outdated information. The move to versioned documentation is a significant step towards improving the overall user experience with JupyterBook.

The Challenge of URL Complexity

The default URL structure provided by RTD can be quite complex, often including language and version slugs. While this structure is functional, it can be less intuitive for users to navigate and remember. A complex URL structure can also make it more difficult to share specific documentation pages, as users may need to manually adjust the URL to reflect the correct version. Therefore, simplifying the URL structure is a key consideration in this proposal.

Proposal: A Simpler URL Structure for JupyterBook Documentation

To address the challenges of URL complexity while still leveraging the benefits of versioned documentation, a simplified URL structure is proposed for JupyterBook's RTD integration. This proposal focuses on creating a more user-friendly and predictable experience for accessing documentation.

The proposed URL structure includes the following key elements:

1. Host the live documentation at jupyterbook.org/docs/.

   • This URL will serve as the entry point for the latest version of the documentation, built from the main branch of the JupyterBook repository. This approach provides a clear and consistent location for users to access the most up-to-date information. By hosting the live documentation at a dedicated /docs/ path, it becomes easier for users to bookmark and share the main documentation URL.

2. Do not use language prefixes (/en/) in the URL.

   • Given the current resources, JupyterBook does not have multi-lingual documentation. Omitting language prefixes keeps the URLs clean and straightforward. This decision can be revisited in the future if translation becomes feasible. Maintaining clean URLs is essential for user experience, especially for users who frequently access the documentation. This simplification ensures that URLs are easy to remember and share.

3. Host older, stable versions at jupyterbook.org/vN/ (e.g., jupyterbook.org/v1/).

   • This structure provides a predictable and intuitive path for users who need to access documentation for specific older versions of JupyterBook. By using a /vN/ format, where N represents the version number, users can easily navigate to the documentation for the version they are using. This predictable structure is crucial for users who may not be using the latest version but still need accurate documentation.

This proposed structure aims to strike a balance between providing versioned documentation and maintaining a user-friendly URL structure. It offers a clear and consistent way for users to access the documentation they need, regardless of the version of JupyterBook they are using.

Benefits of the Proposed URL Structure

The proposed URL structure offers several benefits for JupyterBook users:

• Simplicity: The URLs are clean and easy to understand, making it easier for users to navigate the documentation.
• Predictability: The /docs/ and /vN/ formats provide a predictable structure, allowing users to easily access the documentation they need.
• Shareability: Clean URLs are easier to share and bookmark, improving collaboration and knowledge sharing.
• Maintainability: The structure is easy to maintain and scale as JupyterBook evolves.

Considerations: Learning from Other Projects

In developing this proposal, it's important to consider how other projects handle versioned documentation. This can provide valuable insights and help ensure that JupyterBook adopts a best-practice approach.

Two projects that have been considered are Quarto and Docusaurus. Quarto uses a similar structure, hosting its manual at a dedicated URL (https://pandoc.org/MANUAL.html#epubs). This approach provides a clear and consistent location for the main documentation. Docusaurus, another popular documentation platform, uses a /docs/ path for the latest version and /docs/vN/ for older versions, similar to the proposed structure for JupyterBook. This consistency across projects can help users familiar with these platforms easily adapt to JupyterBook's documentation.

Quarto and Pandoc

Quarto, like Pandoc, provides a clear example of hosting documentation at a dedicated URL. This approach simplifies access to the main documentation and makes it easier for users to find the information they need. By following this pattern, JupyterBook can ensure that its documentation is easily accessible and user-friendly.

Docusaurus

Docusaurus's approach to versioned documentation, using /docs/ for the latest version and /docs/vN/ for older versions, is particularly relevant to the JupyterBook proposal. This structure provides a clear distinction between the latest documentation and documentation for specific versions, making it easier for users to navigate the documentation. Adopting a similar structure can help JupyterBook provide a consistent and intuitive experience for its users.

Conclusion: Towards a More Accessible and User-Friendly Documentation

The proposal to move live documentation to jupyterbook.org/docs/ and simplify the versioning URL structure represents a significant step towards improving the accessibility and user-friendliness of JupyterBook's documentation. By adopting a cleaner and more predictable URL structure, JupyterBook can ensure that users can easily find the information they need, regardless of the version they are using. This change will contribute to a better user experience and help users get the most out of JupyterBook.

The proposed structure, inspired by successful approaches used by projects like Quarto and Docusaurus, provides a solid foundation for managing versioned documentation. By hosting the latest documentation at jupyterbook.org/docs/ and older versions at jupyterbook.org/vN/, JupyterBook can offer a clear and consistent way for users to access the documentation they need. This simplification is crucial for maintaining a user-friendly experience, especially as JupyterBook continues to evolve and new versions are released.

In conclusion, the move to a simplified URL structure is a strategic decision that will benefit JupyterBook users in the long run. By making documentation more accessible and easier to navigate, JupyterBook can empower users to learn and use the platform more effectively. This proposal reflects a commitment to user experience and a desire to provide high-quality documentation that meets the needs of the JupyterBook community.

For more information on documentation best practices, you can visit the Documentation Guide.