2.3 KiB
Introduction
The Helpcenter 3 (HC3) is an Open Telekom Cloud product developed by the Ecosystem Squad introducing a new approach in documentation management. It improves the documentation exchange between delivery partners and the service squads of the Open Telekom Cloud. The documentation platform comes with processes based on GitOps and introduces the following features and benefits:
- Openness,
- Transparency,
- Comprehensive review capabilities,
- Full control during the documentation lifecycle, and
- Documentation as source code.
The target of the platform is to store and maintain all documents in Git. This provides benefits of precise identification of changes and preventing undesired versions to be published. The process is heavily streamlined. Once, those changes are approved and merged, the connected pipelines ensure that the documentation is published fully automated which eases the document auditing and enables users to see the complete history of changes tracked by git itself.
Solution is based on open source components. Its HLD is described at https://docs.otc-service.com/system-config/docsportal.html The implementation is based on these building blocks:
- Restructured Text (RST) as source documentation format,
- Gitea/Github as a repository,
- Zuul as a CI/CD engine for workflows,
- Sphinx as a documentation rendering framework creating for example HTML or PDF documents,
- OpenSearch as a search engine,
- Swift object storage as a storage for documentation,
- Pandoc as a documentation converter, and
- a lot of OTC Infrastructure (ECS, CCE, ELB, ...)
HC3 comes with following features:
- Support of UMN, API, DEV and other public facing documents
- PROD and PREPROD documentation portal:
- docs.otc.t-systems.com
- docs-int.otc.service.com
- Support of all old HC links redirections
- Search functionality
- Mobile-ready UI layout
- Report issue functionality directly on any page
- Suggest documentation fix functionality
- Consolidation of extra content like blueprints, tools, and libraries for developers
- One repository represents one cloud service
- Each squad can control and manage their documentation independently
- Automatization and check jobs across whole documentation lifecycle (from import to release)