zqr10159 opened a new issue, #3966:
URL: https://github.com/apache/hertzbeat/issues/3966
### Description
Problem Statement
Our current documentation structure has become confusing and needs
reorganization. We're facing several issues:
1. Unclear version categorization: Documentation is currently split
between 1.6.x and 1.7.x, making it difficult for users to find version-specific
information
2. Documentation-release mismatch: Some feature documentation is published
before the corresponding GitHub release, creating confusion
3. Lack of development version docs: There's no dedicated space for
documenting features that are already in the codebase but not yet released
Proposed Solution
We need to reorganize our documentation using semantic versioning with a
clear strategy:
Version Structure
1. Stable Versions (v1.6.0, v1.7.0, etc.)
- Documentation for officially released versions
- Each minor version should have its own documentation branch
- Users can easily switch between versions using Docusaurus's built-in
version switcher
2. Development Version (dev or next)
- Documentation for features that are already merged into the codebase
but not yet released
- This serves as a "preview" for upcoming features
- Should be clearly labeled as "unreleased" or "under development"
3. Archived Versions
- Older versions can be marked as archived if needed
- Still accessible but not actively maintained
Prerequisites: Docusaurus Upgrade
Important: Our current Docusaurus version is 2.3.0, which is quite
outdated and has limited version management capabilities. Before implementing
the versioning strategy, we should:
1. Upgrade Docusaurus to the latest stable version (preferably 3.x or
later)
- Newer versions have significantly improved versioning features
- Better performance and security patches
- Enhanced documentation tooling
2. Benefits of upgrading:
- More robust version switcher
- Better handling of next/development versions
- Improved i18n support (if applicable)
- Active maintenance and bug fixes
Call for Volunteers
We're looking for contributors to help with:
- Docusaurus Upgrade Expert: Help upgrade Docusaurus from 2.3.0 to the
latest version, handle breaking changes, and ensure the build works correctly
- Docusaurus Configuration Expert: Someone familiar with Docusaurus
versioning to set up the initial configuration
- Documentation Migration: Help organize and migrate existing documentation
- Version Strategy: Define clear guidelines for when to create new versions
- Testing: Ensure the version switcher works correctly across all versions
and the upgrade doesn't break existing functionality
Resources
- Docusaurus Versioning Docs: https://docusaurus.io/docs/versioning
- Docusaurus Upgrade Guide: https://docusaurus.io/docs/migration
Contributing
If you're interested in helping, please comment below with:
- Which area you'd like to help with
- Your experience with Docusaurus (if any)
- Any suggestions or concerns about this approach
Let's work together to make our documentation more user-friendly and
maintainable!
### Task List
1. Upgrade Docusaurus - Upgrade from 2.3.0 to the latest stable version and
ensure compatibility
2. Reorganize existing documentation - Clean up the current structure and
properly categorize existing docs
3. Set up proper versioning workflow - Configure Docusaurus versioning for
future releases
4. Create versioning guidelines - Document when and how to create new
versions
5. Migrate current docs - Move existing 1.6.x and 1.7.x docs to proper
versioned structure
6. Set up dev/next version - Create and configure the development version
for unreleased features
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail:
[email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
