Architecture diagrams
Context, container and dependency diagrams generated from live infrastructure where possible, then reviewed with the engineers who own each service so errors get corrected early.
Optimisation & Advisory
Technical Documentation & Runbooks
Diagrams, decision records and runbooks that turn a 3 a.m. page into a checklist.
The work
What this actually does
Documentation fails when it drifts. A diagram is drawn during a design review, the service gains three dependencies, and six months later the picture is a polite fiction. We rebuild the core set from what is actually running: the cloud APIs, the cluster, the pipeline definitions and the alert rules. Then we put it somewhere your team will maintain it, next to the code.
The runbooks matter most. Every alert that can wake someone up gets a page-long procedure: what the alert means, how to confirm it, the commands to run, and the point at which to stop and escalate. We test them during business hours by following them literally, because a runbook nobody has executed is a document, not a control.
If any of these sound familiar
- The architecture diagram is at least two years out of date
- Alerts fire with no runbook and no clear owner
- Onboarding a new engineer takes a full month
- Design decisions get re-litigated because nobody recorded them
Scope
What's included
Every engagement on this page covers the following, sized to your setup rather than delivered as a fixed package. If something here is not relevant to you, it comes off the scope and off the price.
Operational runbooks
One runbook per alert, covering symptoms, confirmation steps, remediation commands, rollback and the escalation trigger, stored beside the code that produces the alert.
Decision records
Short architecture decision records capturing the options considered, the choice made and the consequences accepted, so a question from two years ago has an answer.
Onboarding paths
A first-week guide for each role: accounts to request, repositories to read, a small first task and the people to ask about each system.
Documentation as code
Everything lives in Markdown in your repositories, reviewed in pull requests and published by the same pipeline that ships the service it describes.
Freshness checks
Scheduled checks that flag runbooks untouched after a related service change and diagrams that no longer match the infrastructure they claim to show.
What changes
What teams typically see
1 pageTypical runbook length
1:1Runbooks to paging alerts
1 weekNew joiner ramp-up target
Handover
What you keep
Everything produced during the engagement is yours: the repositories, the accounts, the documentation. There is no proprietary layer and nothing to unlicense if you take the work in-house.
- Architecture diagram set for your main services
- A runbook for every alert that pages
- Architecture decision record template and backlog
- Onboarding guide for each engineering role
- Documentation repository wired into your pipeline
Tooling
Tools we use here
A starting point, not a requirement. We work in whatever you already run wherever it does the job.
Kubernetes
Terraform
GitHub
GitLab
Grafana
Prometheus
How it runs
From first call to handover
The same four steps on every engagement. You see each one before it starts and can stop at any of them.
- 01
Inventory what exists
We collect the diagrams, wikis, runbooks and tribal knowledge that exist today, then compare them against the systems and alerts that are actually live.
- 02
Write the core set
Architecture diagrams, alert runbooks and decision records are drafted with your engineers, not for them, so the content is accurate and someone already owns it.
- 03
Test every runbook
We execute each procedure in a non-production environment, correct the steps that do not work, and add the rollback and escalation detail that was missing.
- 04
Wire in the cadence
Documentation lands in your repositories with a review checklist, a stale-content check and an owner named against every page so drift is visible.
Questions
Asked before we start
Our engineers will not maintain documentation. Why would this be different?
Because it lives in the repositories they already work in, changes with the code in the same pull request, and is checked automatically when it goes stale. If a page needs a separate tool and a separate login, it will rot; ours does not.
Can you document a system that nobody fully understands?
That is a common starting point and part of the work. We read the code, the infrastructure and the logs, interview whoever has been closest to it, and mark our uncertainty explicitly rather than guessing. Gaps get listed as questions for the team to confirm.
Who owns the documentation when you leave?
Your team does, from day one. Everything sits in your repositories under your accounts, with named owners per area and a review cadence. We are not the only people who can edit it, and that is deliberate.
How do you keep diagrams from going stale?
Where a diagram can be generated from infrastructure, we generate it and review the output on a schedule. Where it cannot, the diagram is tied to a service owner and checked in the same review as the next change to that service.
Optimisation & Advisory
Often needed alongside this
Optimisation & Advisory
DevOps Assessment & Enablement
A maturity assessment that produces a prioritised roadmap, then hands the team the skills to run it.
- Delivery, reliability and security maturity audit
- Prioritised 90-day improvement roadmap
- Hands-on training, pairing and runbook handover
Optimisation & Advisory
Training & Team Enablement
Your engineers learn to run the platform themselves — through pairing, workshops and internal runbooks.
- Tailored workshops on IaC, Kubernetes and CI/CD
- Pairing and code review on real work
- Internal knowledge base so it stays in-house
Reliability & Performance
Monitoring & Observability
Know what broke, why it broke and who it affects — before your customers have to tell you.
- Prometheus, Grafana, Datadog & CloudWatch
- OpenTelemetry tracing and structured logging
- SLO dashboards and actionable alert routing
Worth a conversation about Technical Documentation & Runbooks?
Bring the specific problem. We will tell you honestly whether this is the service that fixes it, and what it would take.