Documentation in the AI project | Protos technology – the cloud experts

Technically clean, but without understandable track? Anyone who is responsible for the IT manager or architect cloud projects with a focus knows that the best solutions are of little use if their origin, operating logic or automation steps are not documented. Because especially in highly dynamic environments such as AWS, Azure or GCP Documentation not an addition, but critical component – albeit an often invisible.

Documentation in the cloud age: More than a wiki entry

An example from Protos practice shows how essential well-thought-out documentation is today: In a current customer project, we have developed a system for automated ticket analysis with generative AI in the AWS cloud. In addition to the development of a scalable architecture, the implementation of API integrations and the establishment of an efficient ML model, it was clear from the start that every decision, configuration and automation must be comprehensible.

This requirement had several reasons: On the one hand, the documentation was necessary to meet the company's internal security and compliance requirements as part of a 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 had to be transparent and testable afterwards. In addition, the integration into an existing support system such as Jira brought requirements for compliance documentation and required specific security releases. Last but not least, the company and the further development should be handed over to an internal IT team in the long term. Without a complete documentation, the entire project would have been risky, inefficient and in regular operation.

Typical challenges – and how we address them with Protos

Documentation as a product instead of downstream obligation

In the ticket analysis project it was clear from the start: the documentation should not be created at the end, but should be created Comfortable in parallel to implementation.

We used standardized templates in Confluence, for example for architectural decisions, IAM policies and data flows. In addition, a structured souvenir routine was introduced that gave indications of necessary updates every month. We also adjusted our meeting structure: As soon as a decision was made in an appointment, it was directly linked to a corresponding documentation note.

The result was a fluid process – nobody in the team had to “swirl extra time” afterwards to document things. The documentation was seamlessly integrated into everyday work.

Technical depth without confusion

Details are particularly important for cloud projects:
Why did we use which service – and decided against others?
Which Lambda function calls up which model endpoint?
How is the fallback solved in API errors?
Who can read which bucket?

We have such information:

• Stored in architecture -specific microcs sites (one page = an architecture decision according to the concept of the Architecture Decision Records ADR).

• Combined with automated source code references (e.g. via Sphinx documentary in Python modules).

• Supplemented by graphic BPMN models (e.g. Camunda to describe the processes in the analysis pipeline).

Responsibility & topicality

Technical documentation ages quickly. That is why we have determined clear responsibilities:

• There is a “documentary manager” per service (not: author) who checks monthly whether content is out of date.

• Changes in the CI/CD pipeline or on model parameters automatically trigger a documentary checklist that is transferred to the Confluence Board.

• With the interaction of Jira, Git and Confluence, we were able to make sure that the documentary and code never drift too far apart.

Which tools prove themselves in practice

Technical teams document differently than classic project managers – and you need other tools:

• Markdown & Git For documentation close to the source code.

• There is & Confluence For consistent traceability between tickets, architecture resolutions and company details.

• Camunda (BPMN) for modeling and control of process steps (e.g. in ML pipelines).

• Plantum or C4 diagrams Directly in Markdown files for in-repo documentary.

• Sphinx or Mkdocs For technology-related python or API documentation, CI/CD inclusive.

• Miro & Draw.io For visual architecture overviews, embedded in project pairs.

Conclusion: Documentation is operational safety

In cloud environments with dynamic infrastructures, integrated AI and microservices, documentation is much more than just a good practice-it is one Crucial safety factor. It ensures transparency and makes systems audit, enables smooth handover between departments and external service providers, reduces error rates and reduces training times. At the same time, it supports the scalability and reusability of solutions.

For our customers this means that a well thought-out documentation is not a Nice-to-have, but the operational backbone and A central strategy element. Anyone who consistently anchor them creates the basis for more stability, higher implementation speed and sustainable trust.