Documentation in AI projects: the backbone for lasting success
Technically sound, but without a traceable trail? Anyone responsible for cloud projects with a focus on AI as an IT manager or architect knows that even the best solutions are of little use if their creation, operating logic, or automation steps are not documented. This is because, especially in highly dynamic environments such as AWS, Azure, or GCP, documentation is not an add-on but a critical component – albeit one that is often invisible.
Dokumentation im Cloud-Zeitalter: Mehr als ein Wiki-Eintrag
An example from PROTOS’s practice shows how essential well-thought-out documentation is today: In a current customer project, we developed a system for automated ticket analysis with generative AI in the AWS cloud. In addition to developing a scalable architecture, implementing API integrations, and building an efficient ML model, it was clear from the outset that every decision, configuration, and automation had to be documented in a traceable manner.
There were several reasons for this requirement: On the one hand, the documentation was necessary to meet internal security and compliance requirements within the framework of an AI act. On the other hand, various teams were involved in the project – from DevOps to the AI team – and decisions on scaling options, IAM roles, or data pipelines, for example, had to be transparent and verifiable even after the fact. In addition, integration into an existing support system such as Jira placed demands on compliance documentation and required specific security approvals. Last but not least, it should be possible to hand over operation and further development to an internal IT team in the long term. Without complete documentation, the entire project would have been risky, inefficient, and hardly viable in regular operation.
„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.“
Tobias Schulz-Hess, Senior IT-Cloud Architect & Certified Trainer at PROTOS
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.
Fazit: Dokumentation ist Betriebssicherheit
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.
