Documentation guidelines
Documentation is part of the implementation and source of truth.
Audience ownership
Section titled “Audience ownership”| Section | Primary reader | Content rule |
|---|---|---|
| API | Developers and testers using HTTP/OpenAPI. | Every exposed endpoint, authentication, parameter, body, response, error, and executable example. |
| Platform | Customers operating the web console. | Available screens and tasks in plain language, without internal service detail. |
| Technical | Platform developers, operators, support, and AI agents. | Implemented architecture, services, contracts, configuration, operations, failure behavior, and troubleshooting. |
| Internal | Platform team and AI agents shaping future work. | Development philosophy, roadmap, planned concepts, and open decisions clearly labeled as future. |
The former Manual is not a separate section. Its current customer workflows belong under Platform; implemented internals belong under Technical; future telemetry and export ideas belong under Internal.
Synchronization rules
Section titled “Synchronization rules”- Changes to contracts, configuration, deployment, operations, security, tenancy, persistence, or user workflows update documentation in the same change.
- Public API behavior updates the authoritative OpenAPI YAML, generated reference, and relevant API guide. The interactive console consumes that same YAML and must not maintain a second schema copy.
- Cross-module contracts have an authoritative location under Technical contracts, OpenAPI, SQL migrations, or versioned TypeScript packages.
- Accepted technical decisions are captured in ADRs. Questions that are still open belong under Internal until resolved.
- The Internal roadmap is updated when status, sequence, delivery gates, or future scope changes. English and German roadmap pages remain semantically equivalent.
- Platform pages document only currently available web-console behavior. Planned screens are not presented as customer features.
Writing standard
Section titled “Writing standard”Start with the reader’s outcome. Use consistent product terminology, specific actions, bounded examples, and explicit current-versus-planned status. Technical pages include enough ownership, dependency, failure, recovery, and verification detail that a developer or AI agent can navigate the system safely without starting from code.
German text uses correct UTF-8 characters such as ä, ö, ü, and ß.