Restructure Documentation Navigation
Introduction
As we continue to develop and refine our Kubernetes operator, it's becoming increasingly clear that our documentation will need to evolve to accommodate the changing landscape. With multiple guides on the horizon, tied to specific Kroxylicious releases, we'll need to restructure our website's navigation to support this new paradigm. In this article, we'll explore one potential solution: creating per-version "docs landing pages" that provide a centralized hub for accessing documentation applicable to each release.
The Current State of Documentation
Our current monolithic guide has served us well, but as we move forward, it's becoming clear that a more modular approach is needed. With multiple guides on the horizon, tied to specific Kroxylicious releases, we'll need to find a way to organize and present this information in a clear and concise manner. This is where the concept of per-version "docs landing pages" comes in.
Per-Version "Docs Landing Pages"
One potential solution to this problem is to create a per-version "docs landing page" for each Kroxylicious release. This page would serve as a centralized hub for accessing documentation applicable to that specific release. Each landing page would include links to the different sets of documentation, including the guide, Javadoc, and any other relevant resources.
Benefits of Per-Version "Docs Landing Pages"
So, what are the benefits of this approach? For one, it provides a clear and concise way to organize and present documentation for each release. This makes it easier for users to find the information they need, without having to navigate a complex and potentially confusing hierarchy of pages.
Another benefit is that it allows us to maintain a consistent URL structure across releases. For example, the current monolithic docs live at https://kroxylicious.io/docs/v0.10.0/. With per-version "docs landing pages", we can maintain this same URL structure, but with a more modular and flexible approach.
Handling Existing URLs
So, how do we handle existing URLs? For example, the current monolithic docs live at https://kroxylicious.io/docs/v0.10.0/. This is the intuitive URL for the per-release docs landing page. To maintain consistency, we can redirect existing URLs to the new per-version "docs landing pages".
Implementation
So, how do we implement this new approach? Here are the general steps we can follow:
- Create per-version "docs landing pages": We'll need to create a new page for each Kroxylicious release, which will serve as a centralized hub for accessing documentation applicable to that release.
- Add links to documentation: We'll need to add links to the different sets of documentation, including the guide, Javadoc, and any other relevant resources.
- Maintain consistent URL structure: We'll need to maintain a consistent URL structure across releases, using the same URL structure as the current monolithic docs.
- Redirect existing URLs: We'll need to redirect existing URLs to the new per-version "docs landing pages" to maintain consistency.
Conclusion
In conclusion, restructing our documentation navigation to support multiple guides tied to specific Kroxylicious releases is a complex task. However, by creating per-version "docs landing pages" and maintaining a consistent URL structure, we can provide a clear and concise way to organize and present documentation for each release. This approach also allows us to maintain a consistent URL structure across releases, making it easier for users to find the information they need.
Future Directions
As we move forward with this new approach, there are several future directions we can explore. For example, we can consider adding more features to the per-version "docs landing pages", such as:
- Search functionality: We can add search functionality to the per-version "docs landing pages", making it easier for users to find specific information.
- Filtering and sorting: We can add filtering and sorting functionality to the per-version "docs landing pages", making it easier for users to navigate and find the information they need.
- Integration with other tools: We can integrate the per-version "docs landing pages" with other tools and services, such as version control systems and continuous integration/continuous deployment (CI/CD) pipelines.
Introduction
In our previous article, we explored the concept of restructing our documentation navigation to support multiple guides tied to specific Kroxylicious releases. We discussed the benefits of creating per-version "docs landing pages" and maintaining a consistent URL structure across releases. In this article, we'll answer some frequently asked questions (FAQs) about this new approach.
Q: Why do we need to restructure our documentation navigation?
A: As we continue to develop and refine our Kubernetes operator, it's becoming increasingly clear that our documentation will need to evolve to accommodate the changing landscape. With multiple guides on the horizon, tied to specific Kroxylicious releases, we'll need to find a way to organize and present this information in a clear and concise manner.
Q: What are the benefits of creating per-version "docs landing pages"?
A: Creating per-version "docs landing pages" provides a clear and concise way to organize and present documentation for each release. This makes it easier for users to find the information they need, without having to navigate a complex and potentially confusing hierarchy of pages. Additionally, it allows us to maintain a consistent URL structure across releases.
Q: How do we handle existing URLs?
A: We'll need to redirect existing URLs to the new per-version "docs landing pages" to maintain consistency. For example, the current monolithic docs live at https://kroxylicious.io/docs/v0.10.0/. This is the intuitive URL for the per-release docs landing page.
Q: What are the technical requirements for implementing this new approach?
A: To implement this new approach, we'll need to create a new page for each Kroxylicious release, which will serve as a centralized hub for accessing documentation applicable to that release. We'll also need to add links to the different sets of documentation, including the guide, Javadoc, and any other relevant resources. Additionally, we'll need to maintain a consistent URL structure across releases and redirect existing URLs to the new per-version "docs landing pages".
Q: How will this new approach affect our users?
A: This new approach will make it easier for users to find the information they need, without having to navigate a complex and potentially confusing hierarchy of pages. Additionally, it will provide a clear and concise way to organize and present documentation for each release.
Q: What are the potential challenges of implementing this new approach?
A: One potential challenge is that it may require significant changes to our existing documentation and infrastructure. Additionally, it may require additional resources and effort to maintain and update the per-version "docs landing pages".
Q: How will we measure the success of this new approach?
A: We'll measure the success of this new approach by tracking user engagement and feedback. We'll also monitor the number of users accessing the per-version "docs landing pages" and the time it takes for users to find the information they need.
Q: What are the future directions for this new approach?
A: As we move forward with this new approach, we can consider adding more features to the per-version "docs landing pages", such as search functionality, filtering and sorting, and integration with other tools and services. We can also explore ways to improve user engagement and feedback, such as surveys and user testing.
Conclusion
In conclusion, restructing our documentation navigation to support multiple guides tied to specific Kroxylicious releases is a complex task. However, by creating per-version "docs landing pages" and maintaining a consistent URL structure across releases, we can provide a clear and concise way to organize and present documentation for each release. This approach also allows us to maintain a consistent URL structure across releases, making it easier for users to find the information they need.