================================Special Feature Introduction =================================
1. Document Center Experience Optimization
1. Background Issues
The legacy Document Center featured a monolithic documentation system that aggregated content across all business scenarios, resulting in document clutter and disorganized content structure. Users struggled to quickly locate the documentation relevant to their needs within the current system.
2. Solution
Product documentation architecture overhaul: Reorganize the documentation structure based on business scenarios and user roles. This transformation moves away from a one-size-fits-all approach, splitting the content into 6 major business scenarios and 7 tool modules, comprising over 70 manuals.
3. Progress and Outcomes
The new Document Center has been launched with the openEuler 25.03 release.
2. Optimization of Document Production and Publishing Mechanism
1. Background Issues
In the legacy document production model, all documentation was produced and published from the openeuler/docs repository.
(1) For feature SIG members:
- Low efficiency in communication and approval with the Doc SIG, leading to delayed documentation updates.
- Must adhere to the public docs repository’s workflow and standards, limiting flexibility.
- High barrier to entry due to the need to learn the public docs structure and merge processes.
(2) For Doc SIG members:
- Heavy workload in coordinating document integration across various feature SIGs.
- Ambiguous responsibility boundaries, making issue resolution slow.
- Limited domain expertise, affecting the accuracy and completeness of documentation.
2. Solution
Decentralize document production to individual SIG groups.
(1) Document Production:
Previously, all documents were centralized in the docs repository. After the update:
- Foundational feature documentation (e.g., installation, upgrade, and other common configuration guides) remains in the
docsrepository and is centrally managed by the Doc SIG. - Incremental feature documentation (e.g., A-Tune, oeAware, and other extended system functionality) is now maintained within each SIG’s respective code repository.
(2) Document Publishing:
- Each SIG stores the actual document content files and directory structure files (_toc.yaml, which defines chapter hierarchy) in their code repositories.
- By referencing the manual’s directory structure file into the corresponding business scenario or tool’s directory structure file, the feature documentation can be automatically built and published to the website.
3. Progress and Outcomes
The new document production mechanism has been successfully rolled out and implemented in the sig-ai and sig-openStack SIGs for the openEuler 25.03 release. Key benefits include:
(1) For feature SIG members:
- Full flexibility in managing documentation within their own code repositories.
- Ability to update documentation in real time when code changes are made.
- Lower contribution barriers, increased motivation, and improved quality and quantity of documentation.
(2) For Doc SIG members:
- Reduced burden in collecting, integrating, and coordinating documentation across SIGs.
- Can now focus on core tasks such as defining documentation standards and conducting reviews.
================================Community Discussion =================================
Community Meeting
Meeting Topic: openEuler Documentation Upgrade and Refactoring
Meeting Time: Every Monday, 14:15–15:15
Meeting Agenda: Progress and risks of the openEuler documentation refactoring initiative
Contact Us
Mailing List: doc@openeuler.org
Docs Repository: docs: 本项目已经迁移至 AtomGit || This project has been migrated to AtomGit || Linked: https://atomgit.com/openeuler/docs
Access URL
Document Center: https://docs.openeuler.openatom.cn/zh/
新文档很不错
