My Kingdom for some Documentation
Solving documentation for you and your tech team in one post
Have you ever been in a situation where you were asked to support a system or service, but there was no documentation to be found anywhere? Or you have started in a new team, and you want to get up to speed on a system or service, but you cannot find a single document in Notion or Confluence. Or, even worse, you’re working on a greenfield project, and you need to decide how to tag the cloud resources that you’re deploying — ohh, there is no standard, so I’ll have to make one up until I can go back to it! Yup, this will apply to most of us.
I want to use this blog post to cover everyone’s least favourite subject, documentation, but hopefully in a helpful enough way that you can solve the problem of documentation in your tech org for good. Ohh, and the title of this blog post is a tongue-in-cheek borrow of the quote from Shakespeare’s Richard III, and if I remember correctly, used for the Horseback Riding technology breakthrough in Sid Meier’s Civilization 5 game, narrated by Leonard Nimoy.
Documentation Types
So, what exactly do we mean by documentation? There are various types of documentation, including Request for Comments (RFCs), Architecture Decision Records (ADRs), Runbooks, and product support documentation. I won’t be covering more product-focused documentation like Product Requirements Documents (PRDs), or even engineering team-type documentation like team canvases, team social contracts, or team interfaces, etc. I will keep it more technically focused for now.
Let’s get stuck in.
Request for Comments (RFCs)
Request for Comments (RFCs) have been around since the early days of tech, and were created by Steve Crocker whilst working on the development of ARPANET. Steve published the first RFC in 1969, so I think you’ll agree, this has been around for a while and probably serves some usefulness. The Internet Engineering Task Force (IETF) have published many RFC’s since, covering protocols such DNS, DHCP etc. RFCs are meant to address real problems, with a supplied proposal in the format of a standard. That proposal should then undergo discussion with comments from your colleagues/peers/leadership. Everyone who has a question or a piece of feedback should be welcome to chime in. I have found over the years that healthy tech teams regularly participate in community discourse and support each other as we learn and grow together.
Should I use AI to create an RFC document? No. No, you shouldn’t. RFC’s should carry your style, your opinions, and your individuality. If you use AI to create an RFC, then you’re not opening up a healthy opportunity for the rest of the team to give you valuable feedback — and that’s the point.
So, what should an RFC look like? The format below is merely a guide based on things I have picked up and contributed to over the years:
RFC - <insert title>
—----------------------------------------------------------------------------------------------------------------------------
ABSTRACT
This “abstract” section should provide a synopsis of the problem so that reviewers/stakeholders can quickly determine whether their feedback or opinions might be relevant to this RFC.
PROBLEM STATEMENT
This “problem statement” section should include a detailed description of the problem and an explanation of why it’s essential to present a proposal for it.
WHY NOW (Optional)
This “why now” section can include further details of why the defined problem should be tackled now. This might be a detailed business or technical case.
PROPOSAL
This “proposal” section should contain a single detailed proposal to solve the defined problem. If you have more than one proposal, it probably means you weren’t ready to write an RFC yet. You need to make sure you have done the due diligence and dismissed other potential proposal candidates.
SCOPE (Optional)
This “scope” section can include a scope of systems or processes that this proposal is intended for. For example, you may have a tagging standard for AWS, but your team also operates in GCP, but you only want to standardise AWS resource tagging for now.
APPENDIX
This “appendix” section should contain any relevant resources or supporting information that is relevant to the described problem, and provided proposal. Ie. reading materials from SaaS or Cloud vendors.
A simple example to help show the value of an RFC:
RFC - AWS Account+Root Email Naming Convention
—----------------------------------------------------------------------------------------------------------------------------
ABSTRACT
We will soon be creating an entirely new AWS org, and creating multiple accounts within that org. We do not currently have an account naming convention, and this is causing inconsistencies, which is making a bad developer experience. We should also define a root account email structure process to create a seamless experience when managing new AWS accounts and storing the never-to-be-used root account credentials in our password vault.
PROBLEM STATEMENT
Right now we have naming inconsistencies across new AWS accounts, existing AWS accounts, acquisitions etc. This creates a confusing environment for engineers with access to multiple accounts. Furthermore, the admin/root email addresses are inconsistent, which only adds to the confusion.
WHY NOW (Optional)
If we define this standard now, we can use it in our automation and manual AWS account creation process to avoid adding further inconsistencies in our new AWS environments.
PROPOSAL
AWS Account Names Convention
acme-<product_or_initiative>-<optional_workload>-<env>
The regex pattern:
^(acme)-{1}([a-z]+)-?([a-z\-]+)?-?-{1}(dev|staging|prod|sandbox)$
Matching examples:
acme-example-inventory-dev
acme-example-admin-dashboard-dev
acme-data-migration-sandbox
acme-security-tooling-mgmt-prod
AWS Account Root Email Address Convention
We are proposing using a single Google Workspace email group to maintain and manage our root account email addresses.
This email group will only be accessible by Platform Engineering.
aws-admin+<product_or_initiative>-<optional_workload>-<env>@acme.net
The regex pattern:
^(aws-admin)\+{1}([a-z]+)-?([a-z\-]+)?-?-{1}(dev|staging|prod|sandbox)(@{1}acme\.net)$
Matching examples:
aws-admin+data-migration-sandbox@acme.net
aws-admin+example-admin-dashboard-prod@acme.net
aws-admin+example-inventory-prod@acme.net
SCOPE
The scope is only for AWS accounts and root account email aliases.
APPENDIX
https://docs.aws.amazon.com/organizations/latest/userguide/best-practices_member-acct.html#bp_member-acct_define-acct
And that’s it! A simple example to show the art of the possible.
RFCs should be maintained in a version-control system, such as Notion, Confluence, or a git repo (though sometimes you may have non-technical reviewers who might struggle with git). You should have the RFC template as an RFC itself, in case you want to add new sections or change the template in the future.
Technical or non-technical stakeholders can create RFCs if they have a standard that they would like to define. Standards are critical in the world of tech, because the alternative is infinite combinations and permutations of implementations that become extremely difficult to change later down the line. Let’s use the example that you have some compliance work on the horizon, where the controls dictate that all databases should be encrypted at rest. If you didn’t implement a standard early on, you may have production databases that aren’t encrypted at rest. This becomes a nightmare to fix now because there was no standard to follow earlier.
In the new fangled world of AI there is even the opportunity to take an RFC, and create a pipeline where you build codified compliance policies to enforce your standard, using tools like OPA, Cloud Custodian and Prowler to provide guardrails to your product engineering pipelines. I am working on another blog post to cover this exact topic in the near future, with examples!
Ok, so I hope you understand RFCs and how they will help you define standards in your tech org, and encourage healthy discourse from your lovely engineers.
Architecture Decision Records (ADRs)
Architecture decision records (ADRs) are an ideal tool for documenting system and service decisions. They capture all relevant concerns and consequences, and each entry undergoes full peer review before being added to the log.
Where RFCs describe holistic, tech-org-wide standards, ADRs are for a specific service/system. ADRs should be stored as close to your project code repositories as possible. Creating a docs folder in your repo, with an ADR subfolder, is an excellent standard to follow (but you can write an RFC for that, remember!)
So, what should an ADR look like? Again, this is merely an example based on experience over the years:
ADR-XXX: Title
Status: Draft, In Discussion, Decided, Implemented, Abandoned, Superseded
Authors:
Decision Date:
Context / Problem
// Define the problem and explain the context driving the decision. What was the need? Don’t write war and peace; keep it short and succinct, linking all relevant materials.
Decision & Rationale
// Explain your decision in one sentence and then explain your rationale in bullet point format
(Expected or Known) Consequences
// Explicitly list down the consequences. Also, what about the consequences of consequences (second-order thinking)?
Considered Options (and why they haven’t been chosen?)
// List down all the other options you considered with their pros/and cons. For each, explain with one sentence why you didn’t pick them.
Appendix / References
// Add additional materials that can give more context or are relevant to the decision.
Update Log:
// After the ADR moves out of Draft status, log changes here. A good analogy for this log is having them as meaningful commit messages.
Example Log:
2025-10-01: Moved the ADR to In Discussion
2025-10-10: Added an extra considered option: XYZ
2025-10-12: Abandoned the ADR. The problem is invalid; no solution is needed.
Let me provide an example to show how this looks out in the wild:
ADR-001: Adopt Static Site Generator for Company Blog
Status: Implemented
Authors: Sarah Chen (Lead Developer), Marcus Thompson (Content Lead)
Decision Date: 15 March 2025
Context / Problem
Our current WordPress blog requires constant security patches, plugin updates, and dedicated hosting infrastructure costing £200/month. The marketing team spends roughly 3 hours per week dealing with performance issues and spam. We need a more maintainable solution that reduces operational overhead whilst improving site performance for our growing audience.
Related: Performance audit report, Security incident log Q4 2024
Decision & Rationale
We will migrate our company blog to Astro, a static site generator, hosted on Cloudflare Pages.
Performance: Static sites deliver pre-rendered HTML, eliminating database queries and dramatically improving page load times (estimated 3x faster)
Security: No server-side code execution means virtually no attack surface for common exploits
Cost reduction: Hosting costs drop from £200/month to approximately £15/month, a 92% saving
Developer experience: Component-based architecture allows us to use React components where needed whilst maintaining excellent performance
Content workflow: Integration with our existing GitHub workflow means content can be version-controlled and reviewed via pull requests
Maintenance burden: Eliminates plugin updates, database maintenance, and reduces security patching to essentially zero
(Expected or Known) Consequences
Positive:
Significantly faster page loads improve SEO rankings and user experience
Reduced hosting costs free up budget for content creation tools
Version-controlled content prevents accidental deletions and provides full audit history
Development team can focus on features rather than maintenance
Negative:
Content editors must learn Markdown and basic Git workflows (estimated 2-day learning curve)
Dynamic features (comments, search) require third-party integrations rather than plugins
Migration effort estimated at 40 developer hours plus 20 hours for content team training
Second-order consequences:
Improved performance may increase organic traffic, requiring us to scale content production capacity
Version control workflow might slow down urgent content updates initially until team adjusts
Success could lead to requests to migrate other properties (documentation, knowledge base) to similar architecture
Considered Options (and why they haven’t been chosen?)
Next.js with ISR (Incremental Static Regeneration)
Pros: Familiar React ecosystem, flexible hybrid rendering, excellent developer experience
Cons: More complex infrastructure, higher hosting costs than pure static, overkill for our content-focused use case
Why not chosen: We don’t need the complexity of a full React framework when our blog is primarily static content
Hugo
Pros: Extremely fast build times, mature ecosystem, zero JavaScript by default
Cons: Go templating is less familiar to our team, limited component reusability, steeper learning curve
Why not chosen: Team familiarity with JavaScript ecosystem outweighs Hugo’s raw speed advantages
Continue with WordPress using managed hosting
Pros: Zero migration effort, familiar to content team, extensive plugin ecosystem
Cons: Doesn’t address core performance or cost issues, simply shifts maintenance burden to vendor
Why not chosen: Fails to solve the fundamental problems we’re experiencing with dynamic CMS architecture
Ghost CMS
Pros: Modern Node.js-based CMS, better performance than WordPress, cleaner interface
Cons: Still requires database and server infrastructure, doesn’t eliminate maintenance burden, subscription costs
Why not chosen: Keeps us in the dynamic CMS paradigm that’s causing our current issues
Appendix / References
Astro documentation
Migration plan and timeline
Content team training materials
Cloudflare Pages pricing
Lighthouse performance comparison
Update Log
2025-02-15: Moved the ADR to In Discussion
2025-02-22: Added Hugo as a considered option after team feedback
2025-03-01: Updated cost analysis with actual Cloudflare Pages pricing
2025-03-08: ADR approved; status changed to Decided
2025-03-15: Migration completed successfully; status changed to Implemented
2025-03-20: Added note about second-order consequence regarding scaling content production
The benefits of ADRs are not just for now; they are instrumental in the future as well. For example, if you have a new joiner on your team who is curious about how the team reached past decisions and would like more information, they can read the ADRs and logs to see the sequence of decisions. They could even point an AI agent at it to get a decision-tree output. This will allow them to paint a clear mental picture and get up to speed in record time.
Should you use AI to create your ADR documents? Maybe. Partially. At the bare minimum, you should make sure you have thoroughly reviewed the document to ensure it meets its intended purpose — a log of why and what.
As you can see, ADRs are extremely valuable and definitely worth introducing into your tech org if you haven’t already.
Runbooks
In the fast-paced world of IT operations and DevOps, having clear, actionable documentation can mean the difference between a swift resolution and hours of troubleshooting chaos. Enter the runbook: a detailed, step-by-step guide that documents routine operational procedures and responses to common incidents. Think of it as a recipe book for your infrastructure, where each recipe outlines precisely how to handle specific situations, from routine maintenance tasks to urgent production incidents.
Runbooks serve as the institutional knowledge of your organisation, capturing the expertise of your most experienced team members and making it accessible to everyone. They’re particularly valuable during high-pressure situations when stress levels are high, and memories might fail. By documenting procedures in advance, teams can respond consistently and efficiently, regardless of who’s on call or what time an incident occurs. This consistency not only reduces mean time to resolution (MTTR) but also helps prevent minor issues from escalating into major outages.
The beauty of a well-crafted runbook lies in its ability to democratise knowledge across your organisation. Junior engineers can confidently handle tasks that might otherwise require senior expertise, whilst experienced team members can focus on more complex challenges rather than repeatedly explaining routine procedures. Moreover, runbooks serve as living documents that evolve with your infrastructure, capturing lessons learnt from past incidents and continuously improving your operational resilience. Whether you’re managing cloud infrastructure, maintaining legacy systems, or orchestrating complex deployments, runbooks are an essential tool for building reliable, maintainable systems.
Let’s look at a template example for runbooks:
## Runbook Template
```markdown
# [Service/System Name] - [Procedure/Incident Type]
## Metadata
- **Last Updated:** [Date]
- **Owner:** [Team/Individual Name]
- **Severity Level:** [Critical/High/Medium/Low]
- **Estimated Time:** [Expected duration]
- **Required Access:** [List of systems, credentials, or permissions needed]
## Overview
[Brief description of what this runbook covers and when it should be used]
## Prerequisites
- [Required access level or credentials]
- [Necessary tools or software]
- [Environmental conditions or system states]
## Impact Assessment
**Affected Services:** [List of impacted services]
**User Impact:** [Description of how users are affected]
**Business Impact:** [Revenue, SLA, or other business implications]
## Detection and Diagnosis
### Symptoms
- [Observable symptom 1]
- [Observable symptom 2]
- [Observable symptom 3]
### Monitoring Alerts
- [Alert name/type that triggers this runbook]
- [Dashboard or monitoring tool to check]
### Diagnostic Steps
1. [Step to verify the issue]
```
[Command or action]
```
**Expected Output:** [What you should see]
**If Different:** [What it might indicate]
2. [Next diagnostic step]
## Resolution Steps
### Step 1: [Action Name]
**Description:** [What this step accomplishes]
```
[Command or detailed instructions]
```
**Verification:** [How to confirm this step succeeded]
**Rollback:** [How to undo this step if needed]
### Step 2: [Action Name]
**Description:** [What this step accomplishes]
```
[Command or detailed instructions]
```
**Verification:** [How to confirm this step succeeded]
**Rollback:** [How to undo this step if needed]
[Continue for all steps...]
## Verification and Testing
1. [Check to confirm resolution]
2. [Test to ensure service is healthy]
3. [Monitor for [X] minutes to ensure stability]
## Communication Plan
- **Stakeholders to Notify:** [List of people/teams]
- **Communication Channels:** [Slack channel, email list, status page]
- **Status Update Template:** [Brief template for updates]
## Escalation Path
**If resolution fails after [X] attempts or [Y] minutes:**
1. Escalate to: [Next level contact/team]
2. Contact Method: [Phone/Pager/Slack]
3. Additional Context to Provide: [Specific information needed]
## Post-Incident Actions
- [ ] Update incident ticket with resolution details
- [ ] Document any deviations from this runbook
- [ ] Schedule post-mortem if severity warrants
- [ ] Update monitoring or alerting if needed
- [ ] Record incident in knowledge base
## Related Documentation
- [Link to architecture diagram]
- [Link to related runbooks]
- [Link to system documentation]
## Revision History
| Date | Author | Changes |
|------|--------|---------|
| [Date] | [Name] | [Description of changes] |
## Notes and Gotchas
- [Important caveats or common mistakes]
- [Known issues or limitations]
- [Tips from past experiences]
I won’t provide an example in this case because this blog post would otherwise become too long, but please reach out if you have any questions or would like to discuss examples.
Should you use AI to create runbook documents? Yes. Yes, you should. However, you absolutely must review the runbook and game it with your teammates. Runbooks should be Agentic-friendly as well, because you will likely be using AI-automation to run them.
You should make sure there are housekeeping rules stating that any changes in and around systems/services documented in runbooks must be updated.
Runbooks can be incredibly useful for teams working within a DevSecOps culture, where supporting a system/service requires a defined process. Runbooks can be in your documentation centre, in your git repository for the relevant system/service, or both.
Product support documentation
Product support documentation is the supporting documentation for your products. The why, what and how. This documentation type is for internal consumption only. You will likely have public-facing product support documentation in the form of user guides, workshops, etc. The product support documentation I am speaking of in this post is what you and your tech team use to understand a service/system and how it adds to a value stream.
I will not give a template for this documentation type, because this should be a standard that you or your team define, using an RFC.
Should you use AI to create product support documentation? Yes. Yes, you should. This is exactly the sort of thing AI is meant for. The product support documentation should also be Agentic-friendly, so you can retrieve summaries of what different products do within the value stream and how they all piece together.
Product support documentation should sit within a given system/service code repository, and it should be continuously synced to your documentation centre. The reason for keeping it in code is so that when your engineers are working on delivery, they also have a checklist item to remind their agent fleet to update any product support documentation with the applied changes.
Conclusion
To Summarise:
I really hope this post is helpful to the community. Documentation is not a particularly exhilarating subject, but an absolute necessity in the tech world.
Without documentation, we would not have the internet; we would not have the very devices you’re sitting down to read this post on — in fact, we wouldn’t have modern civilisation.
I will be sharing some agentic skills in the near future to help create runbooks, architectural decision records, etc.
If you have any comments or questions, please reach out to me.