Regulatory audit documentation and operational runbooks have more in common than most teams realize. Both need to answer the same basic questions: what was the system doing, who made the decision, when, and what happened next. Teams that find audits least disruptive are usually the ones that already write documentation for incidents and handovers as if an external reviewer might read it later.
CRA Article 13 and Annex I Part II require manufacturers to document security properties, update mechanisms, and vulnerability handling procedures. AI Act Article 11 requires technical documentation for high-risk AI systems covering system purpose, architecture, and human oversight mechanisms. DORA Article 17 requires ICT incident logs with timestamps, classification, and evidence of the response taken. These are not separate document types — they are the same operational records, written with enough structure to survive external review.
WHAT_SURVIVES_AUDIT
Documentation that fails under scrutiny is usually documentation written primarily to satisfy an internal review process. It uses internal abbreviations, assumes prior context, and describes outcomes without explaining decisions. An auditor or incident responder coming in cold cannot reconstruct what happened. Neither can a team member who joins six months after the original author left.
Documentation that holds up is written for a reader with no ambient context: clear statements of what the system does, why a decision was made rather than just what was decided, what state the system was in at a given point, and who was responsible for each step. That sounds simple. It is not common.
"Good documentation is shared memory with structure attached."
RUNBOOKS_THAT_WORK
Runbooks fail when they skip steps that seem obvious to the author. During an incident, obvious is not available. Write runbooks with explicit verification steps, expected outputs at each stage, and decision criteria for when to proceed versus escalate. Per-environment configuration differences should be stated explicitly, not referenced from a separate system that might not be accessible during the outage.
Host staging
HostName 192.168.1.10
User deploy
IdentityFile ~/.ssh/id_ed25519_stagingA checked-in SSH config is a small example of operationally useful documentation: it reduces friction for new contributors, survives staff rotation, and does not live in a chat window that gets archived. The same principle applies to environment bootstrap sequences, rollback commands, and log query patterns.
DECISION_LOGS
For regulated systems, the most valuable document is often the one that explains why a design decision was made — not just what was built. Under the AI Act, DORA, and the CRA, you may need to demonstrate that you understood the risks of a particular approach and chose it deliberately. A short decision log entry with the date, the options considered, the reasons for the choice, and the person who approved it is worth far more than a technically accurate architecture diagram with no context attached.
- Keep common operational commands in reviewed scripts inside the repository, not in chat history that may be archived or lost.
- Write runbooks with explicit verification steps and expected outputs at each stage — not just the happy path.
- Document decisions with dates, alternatives considered, and the reasoning behind the choice — especially for security, data handling, and AI system design.
- Use
git worktreeconventions that keep urgent fixes and ongoing feature work in clearly separated contexts.