forked from docs/internal-documentation
52 lines
2.3 KiB
ReStructuredText
52 lines
2.3 KiB
ReStructuredText
============
|
|
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.
|
|
|
|
.. figure:: /_static/images/helpcenter_gitops.png
|
|
|
|
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)
|