If we document today in a comprehensible manner why a particular model parameter was chosen or how an API fallback works, then tomorrow we will enable smooth knowledge transfer, secure further developments, and reliable audits. Without this transparency, long-term secure operation would be irresponsible—and every further development would be a shot in the dark
Typical challenges – and how we address them at PROTOS
Documentation as a product rather than a downstream obligation
In the ticket analysis project, it was clear from the beginning that the documentation should not be created at the end, but rather in parallel with implementation.
To this end, we used standardized templates in Confluence, for example for architecture decisions, IAM policies, and data flows. In addition, a structured reminder routine was introduced that provided monthly notifications of necessary updates. We also adjusted our meeting structure: as soon as a decision was made in a meeting, it was immediately linked to a corresponding documentation note.
The result was a fluid process – no one on the team had to “make extra time” afterwards to document things. The documentation was seamlessly integrated into the daily work routine.
Technical depth without complexity
Details are particularly important in cloud projects:
Why did we use this service and not another?
Which Lambda function calls which model endpoint?
How is the fallback handled in the event of API errors?
Who is authorized to read which bucket?
Such information we have:
- stored in architecture-specific microsites (one page = one architecture decision according to the concept of Architecture Decision Records ADR),
- combined with automated source code references (e.g., via Sphinx documentation for Python modules),
- supplemented by graphical BPMN models (e.g., Camunda for describing the processes in the analysis pipeline).
Responsibility & timeliness
Technical documentation quickly becomes outdated. That is why we have established clear responsibilities:
- Each service has a “documentation manager” (not an author) who checks monthly whether content is out of date.
- Changes in the CI/CD pipeline or to model parameters automatically trigger a documentation checklist, which is transferred to the Confluence board.
- Through the interaction of Jira, Git, and Confluence, we were able to ensure that documentation and code never drift too far apart.
These tools prove themselves in practice
Technical teams document differently than traditional project managers – and they need different tools:
- Markdown & Git for documentation close to the source code.
- Jira & Confluence for end-to-end traceability between tickets, architectural decisions, and operational details.
- Camunda (BPMN) for modeling and controlling process steps (e.g., in ML pipelines).
- PlantUML or C4 diagrams directly in Markdown files for in-repo documentation.
- Sphinx or MkDocs for technical Python or API documentation, including CI/CD.
- Miro & draw.io for visual architecture overviews, embedded in project spaces.
Conclusion: Documentation ensures operational safety
In cloud environments with dynamic infrastructures, integrated AI, and microservices, documentation is much more than just good practice—it is a crucial security factor. It ensures transparency and makes systems auditable, enables smooth handoffs between departments and external service providers, reduces error rates, and shortens training times. At the same time, it supports the scalability and reusability of solutions.
For our customers, this means that well-thought-out documentation is not a nice-to-have, but rather the operational backbone and a central strategic element. Those who consistently implement it lay the foundation for greater stability, faster implementation, and lasting trust.
