The gap between a Senior Cloud Engineer and a Principal Cloud Engineer in the UK is £25,000 a year. IT Jobs Watch puts the UK median for Senior Cloud Engineer roles at £75,000, rising to £90,000 in London, while Principal Cloud Engineer roles command a median of £100,000. At London scale-ups and the big tech firms, Staff and Principal positions reach £130,000 to £180,000. Here is the uncomfortable part: the skill that closes that gap is not Kubernetes, not a sixth certification, and not another cloud platform. It is technical writing for engineers, the least glamorous capability in the profession and the one that most reliably separates engineers who reach Principal from engineers who plateau at Senior.
Most engineers respond to the Senior plateau by doing more of what got them there: deeper technical work, more code, another certification. This fails for a structural reason. Will Larson, author of Staff Engineer, observes that most engineers reach Senior within five to eight years, after which promotion becomes exceptional rather than expected. The decision is no longer made by a manager who watches you work. It is made by a promotion committee or calibration process that reads documents about you, often written by you, and has never seen your code. An engineer who cannot produce a clear design document, a persuasive decision record, or a credible promotion packet is invisible at exactly the moment visibility matters most. The cost is measured in years: Larson describes engineers who lose a promotion cycle or two simply because a new manager arrived and found no written evidence of their impact.
The fix is not becoming a novelist. It is learning to produce four specific documents well, using three frameworks that make writing faster rather than slower. Amazon proved the model at scale: Jeff Bezos banned PowerPoint from senior meetings in 2004 and replaced it with narrative memos read in silence at the start of each meeting, on the logic that structured prose forces better thinking than bullet points ever can. That culture built the most successful cloud business in history. This post covers the four documents that carry a cloud career from Senior to Principal, the frameworks that make them quick to produce, and a twelve month roadmap for building the writing habit without hating every minute of it.
Why Technical Writing for Engineers Is a Career Skill, Not a Chore
The market context makes the case before any framework does. ONS analysis published in June 2025 found that 28% of working adults in Great Britain now work in a hybrid pattern, and that hybrid working concentrates precisely where cloud professionals sit: 45% of workers earning £50,000 or more hybrid work, and degree holders are ten times more likely to do so than workers with no qualifications. Earlier ONS business survey data found the information and communication industry has the highest rate of hybrid working of any sector in Britain at 49%. If half of your colleagues are not in the room, the document is the room. Influence that used to travel through whiteboard sessions and corridor conversations now travels through design docs, decision records, and asynchronous review threads, or it does not travel at all.
The cost of getting this wrong is significant, though the best-known figures need a caveat. Grammarly and The Harris Poll estimated in 2022 that poor communication costs US businesses up to $1.2 trillion annually, roughly $12,500 per employee per year, with business leaders reporting around 7.5 hours per worker per week lost to unclear communication. Those are US figures, in US dollars, and they are survey estimates rather than audited costs. No equivalent UK study exists. But the mechanism they describe will be familiar to anyone who has sat through a third meeting rescheduled because the first two produced no written decision, or watched two teams build incompatible solutions to the same problem because the design existed only in someone’s head.
Tanya Reilly, author of The Staff Engineer’s Path, makes frequent, effective communication one of the defining behaviours of the Staff role. Will Larson goes further: Staff engineers write less code than they used to, and some write none, because their leverage has moved from the codebase to the documents that direct what goes into the codebase. This mirrors the shift covered in our guide to technical mentoring as career capital: past Senior level, your value is measured by how much you multiply other engineers, and writing is the multiplication instrument that scales furthest. A conversation influences one team once. A well-written decision record influences every team that reads it for the next five years.
The Four Documents That Do the Career Work
Treat these as a progression, not a menu. Each one takes the same core skill and applies it at a larger blast radius, and each maps to a career stage.
The Architecture Decision Record: Your Entry Point
The ADR is the ideal first document for engineers who dislike writing because it is short by design. Michael Nygard’s original 2011 formulation, which remains the standard, specifies a one to two page text file with a title, a status, the context that created the decision, the decision itself stated in the active voice, and the consequences, including the negative ones. The UK’s Government Digital Service has adopted the pattern in the GDS Way, recommending ADRs live in version control alongside the code and that superseded records are marked rather than deleted, which tells you how mainstream the practice has become in serious UK engineering organisations.
The career value of ADRs is disproportionate to their size. AWS prescriptive guidance on the practice notes that project teams commonly spend 20 to 30% of their time coordinating with other teams, and that a written record of each significant decision cuts that coordination cost by killing the recurring “why did we do it this way” conversation. For the individual engineer, every ADR you author is a permanent, dated, searchable artefact with your name on it demonstrating architectural judgement. When a promotion case asks for evidence of technical leadership, a trail of accepted ADRs is exactly that evidence, and it accumulates while you do your normal job. At Senior level, aim to author the ADR for every significant decision your team makes. It is fifteen minutes of writing that most of your peers will not bother to do.
The Design Document: Where Senior Becomes Staff
The design doc is the document that most clearly gates the jump to Staff and Principal work. Malte Ubl, who spent eleven years at Google rising to Principal Engineer before becoming CTO of Vercel, describes Google’s design docs as relatively informal documents written before a project starts, focused on the high level implementation strategy and, critically, the trade-offs. The emphasis on trade-offs is the point. A Senior engineer can describe a solution. A Staff engineer describes the three solutions considered, the failure modes of each, and why the chosen one loses least, in a form that lets twenty reviewers stress-test the thinking before a line of code exists.
For cloud professionals the design doc has a specific advantage: cloud architecture decisions are expensive to reverse. A migration approach, a landing zone structure, or a multi-region failover pattern committed without a reviewed design becomes a six figure remediation later. Engineers who consistently produce designs that survive review develop a reputation that reaches beyond their team, and reputation beyond your team is the raw material of Staff promotion. This is the same principle explored in our post on high-stakes performance situations: the moments that define careers are the ones with an audience, and a circulated design doc is a performance with a larger audience than any meeting.
The Strategy Document: The Principal Engineer’s Instrument
Engineering strategy sounds grander than it is. Larson’s advice is deliberately deflating: write five design documents, then synthesise what they have in common into a short statement of how your organisation makes this class of decision, because good engineering strategy is boring. A strategy document for a cloud platform team might be two pages establishing when teams build on the paved road versus when exceptions are granted, or which workloads belong on Kubernetes versus serverless and who decides. It converts your individual judgement into organisational default, which is the literal job description of a Principal engineer.
Few engineers ever write one, which is precisely the opportunity. A Senior engineer who produces a credible strategy document is performing the Principal role before holding the title, and promotion committees respond to evidence of already operating at the next level far more than to potential.
The Promotion Packet and Brag Document: The Record That Survives Reorganisations
The final document is about you. Julia Evans popularised the brag document: a running record, updated fortnightly, of what you shipped, the outcomes it produced, and the people you helped, growing to five or ten pages across a year. Larson’s version is more pointed. He advises writing your Staff promotion packet long before anyone asks for it, using it as a gap analysis, and keeping it current, because managers change and a new manager who has seen none of your work can cost you years. Your memory is not a durable store. Your manager’s memory is worse. A document survives both.
The brag document also feeds every other career artefact you produce, from performance review submissions to the CV itself. We covered the receiving end of this in your CV is your architecture document: the engineers who can evidence impact with specifics are drawing on records they kept at the time, not reconstructing history the night before an application.
Three Frameworks That Make Writing Faster
Engineers who hate writing usually hate one specific thing: staring at a blank page trying to sound impressive. All three frameworks below eliminate that problem by making structure a solved problem before you type a word.
Bottom Line Up Front
BLUF is a US military communication standard with one rule: state the conclusion first, then the supporting detail. Applied to engineering documents, it means the first paragraph of your design doc says what you propose and what it costs, the first line of your status update says whether the project is on track, and the first sentence of your incident summary says what broke and whether it is fixed. Senior readers, who decide promotions, read the first paragraph of everything and the whole of almost nothing. BLUF ensures the paragraph they read is the one that matters. It also destroys the blank page problem: you always know what your conclusion is, so you always know your first sentence.
The Pyramid Principle and SCQA
Barbara Minto’s Pyramid Principle, developed at McKinsey in the 1970s and still the consulting industry’s writing standard, extends BLUF into a full structure: lead with the answer, then group your supporting arguments beneath it, with each level summarising the one below. Its opening pattern, SCQA, gives you the first page of any document for free. Situation: the stable context everyone agrees on. Complication: what changed or broke. Question: the question this raises. Answer: your proposal. Larson explicitly recommends SCQA as the structure for engineering RFCs, which means one pattern serves your decision records, your design docs, and your strategy documents. Four sentences, and the document has a spine.
Start Small and Iterate
The AWS guidance on decision records contains the most liberating advice in this entire discipline: start by capturing decisions in a few sentences, then iterate. A one paragraph ADR that exists beats a comprehensive design doc that does not. Amazon’s own document culture works the same way, with the one page press release written first and the six page narrative built from it. Write the one-pager. Circulate it. Let review comments tell you which sections deserve expansion. Engineers who treat documents as living drafts rather than finished monuments write ten times more, and the volume is what builds both the skill and the paper trail.
The Twelve Month Writing Roadmap
Months one to three are about volume at small scale. Author an ADR for every significant decision your team makes, using Nygard’s template, capped at one page. Take Google’s free Technical Writing One course, which was built for exactly this audience: engineers, not writers, and teaches the basics of active voice, short sentences, and audience awareness in a few hours. Start the brag document now and update it fortnightly. Expected output: eight to twelve ADRs and a two page brag document. Time cost: under an hour a week.
Months four to six move to the design doc. Volunteer to write the design for the next meaningful piece of work your team takes on, structured with SCQA and capped at three pages. Circulate it for written review rather than presenting it in a meeting, and treat every confused comment as data about your writing rather than your reviewers. Draft your promotion packet in Larson’s sense: not to submit, but to find the gaps. The gaps become your work selection criteria for the rest of the year.
Months seven to twelve raise the blast radius. Write a design doc for a problem that crosses team boundaries, because cross-team artefacts are what calibration committees recognise as Staff-level scope. Synthesise your accumulated ADRs into a first strategy document, even if only two pages, and share it with your engineering leadership. Convert one internal document into an external one, a conference talk proposal or a public blog post, which compounds the same work into market visibility. By month twelve you have a promotion case that consists of evidence rather than assertion, and a portfolio of writing that travels with you if the promotion does not arrive where you are.
What AI Changes, and What It Does Not
It is reasonable to ask whether AI assistants make this skill obsolete. The 2025 evidence points the other way. The DORA State of AI-assisted Software Development report, drawing on around 5,000 practitioners globally, found 90% of software professionals now use AI, spending a median of two hours a day with it. Its central finding was that “AI doesn’t fix a team; it amplifies what’s already there,” and it names a healthy internal data ecosystem, meaning documentation and architectural knowledge, as a core capability determining whether AI investment pays off at all. Your ADRs and design docs are no longer just career artefacts. They are the context that makes your organisation’s AI tooling useful, which makes the engineers who produce them more valuable, not less.
The same year’s Stack Overflow Developer Survey, with over 49,000 global responses, found 84% of developers using or planning to use AI tools while trust in AI accuracy fell to 29%, down from 40% previously. That gap is the career argument in miniature. AI can generate fluent prose on demand. What it cannot do is decide which decision deserves a record, judge which trade-off matters to this audience, or stand behind a recommendation in calibration. AI has raised the floor of technical writing for engineers. Judgement about what to write, for whom, and why is now the entire differentiator, and that judgement is built only by writing.
Common Pitfalls and the ROI Case
Four failure modes account for most abandoned writing habits. The first is perfectionism: treating every document as permanent and polishing drafts nobody has asked for, when a rough one-pager circulated today outperforms a polished six-pager circulated never. The second is writing for yourself rather than the reader, producing implementation detail for an audience that needed trade-offs and costs. The third is private writing: documents that live in personal notes or unshared drives create no visibility and therefore no career value, so default everything to the team wiki or the repository. The fourth is stopping when it gets uncomfortable. The first design doc that comes back covered in critical comments feels like failure; it is actually the entire mechanism working, because every comment is review you received before production did.
One pitfall deserves special mention for this audience: hiding behind technical density. Cloud professionals often equate detail with credibility and produce documents only three people can parse. Reilly’s guidance for stuck decisions is instructive here: reduce the issue to three bullet points and one call to action. The most senior engineers write the simplest documents, because they are writing to be acted on rather than to be admired.
The ROI Calculation
The investment is modest and measurable. Google’s Technical Writing courses are free and take a few hours. Nygard’s ADR template, the GDS Way guidance, and Larson’s and Evans’ essays cost nothing. The recurring cost is roughly one hour a week in months one to three, rising to perhaps three hours a week when a design doc is in flight, drawn largely from time currently spent in meetings that a document would have prevented.
The return is the £25,000 median gap between Senior and Principal Cloud Engineer roles in the UK, and materially more at the London scale-ups paying £130,000 to £180,000 for Staff and Principal positions. Against a realistic eighteen month to three year timeline from starting the habit to landing the promotion, an outlay of under 150 hours a year returning a £25,000 permanent salary uplift is a payback measured in weeks of the new salary. No certification in the cloud ecosystem approaches that ratio. Writing is the rare career investment that simultaneously builds the skill, produces the evidence, and performs the role you are asking to be given.
Next Steps
This week:
- [ ] Write one ADR for a decision your team made recently, using Nygard’s context, decision, consequences structure, maximum one page
- [ ] Create your brag document and backfill the last three months from your calendar and closed tickets
- [ ] Enrol in Google’s free Technical Writing One course
This month:
- [ ] Author the ADR for every significant team decision as it happens
- [ ] Volunteer to write the design doc for your team’s next meaningful project, using SCQA
- [ ] Draft the first version of your promotion packet and identify the two biggest evidence gaps
- [ ] Move any private technical notes with team value onto the shared wiki or repository
Useful Links
- Google Technical Writing Courses – free, self-paced courses built for engineers
- Documenting Architecture Decisions – Michael Nygard – the original ADR article
- The GDS Way: Documenting Architecture Decisions – UK government engineering guidance on ADRs
- AWS Prescriptive Guidance: Architectural Decision Records – vendor guidance including the ADR process
- Design Docs at Google – Malte Ubl – how Google structures pre-implementation design documents
- StaffEng – Will Larson – guides and interviews on reaching Staff-plus roles
- Get Your Work Recognized: Write a Brag Document – Julia Evans – the brag document method
- ONS: Who Has Access to Hybrid Work in Great Britain? – official UK hybrid working data
