Documentation that works the way developers actually work
AWS PDFs weren't a reading experience problem. They were a developer workflow problem — reproduced at scale across every implementation, every debugging session, every architecture review.
30% faster information discovery
200,000+ assets improved
WCAG 2.1 AA
First-ever compliance
Solution in production
Same content, redesigned system — built for information retrieval under real development conditions, not for reading from start to finish.
The problem
The brief was wrong. I changed it.
AWS documentation spans 200+ services, 200,000+ assets, 11 languages. The PDF hadn't been redesigned in years, and the conventional framing was clear: the PDFs look outdated, refresh them.
I rejected that framing. Visual refresh projects don't get engineering buy-in and don't justify the investment level this problem required.
Developer interviews gave me the real frame: developers weren't reading these documents — they were using them as tools. Mid-implementation. Mid-debugging. Mid-review with three other engineers. When you need a specific code parameter under pressure and can't find it in 10 seconds, that's not a reading failure. It's a development workflow failure at millions of sessions per day.
Documentation isn't consumed at the start of the workflow. It's referenced throughout.
Problem audit
Audit of the existing AWS documentation PDF — 5 systemic failures across every document.
Dense content — 9.2pt base font
Accessibility — fails WCAG 2.1 AA on contrast and size
Weak hierarchy — headings indistinct, scanning impossible
Truncated elements — code blocks and images broken across page breaks
Difficult scanning — no visual anchors for implementation-specific content
Five failures. One root cause.
The PDF generation pipeline was built for publishing, not for use. Fix that at the system level and you fix all five at once, across 200,000 documents.
The instinct was to scope narrow: fix the font, patch the contrast failures, ship. Systemic scope was the only path to systemic impact.
To understand why these failures mattered, the use context had to be clear first. Developer interviews surfaced four distinct, high-stakes scenarios — all of them cases where the document had to work reliably under real conditions.
Use Cases
Technical Review
Printable artifact for architecture reviews, annotations, collaborative discussions
Four high-intent use cases — all requiring reliable document performance under real conditions.
Every one of these use cases was being actively undermined by the existing system. Before any exploration, I established five constraints to govern every decision that followed.
Five constraints set before a single layout exploration began.
Design Decisions
The density assumption was wrong — and I had to kill it with data
Density works when you have time. Under debugging pressure at 11pm, it's the enemy of the task.
I ran three layout explorations — Dense, Readable, Wide — tested with 12 developers in timed implementation tasks. Readable produced 30% faster task completion, even though it generated longer documents. The density assumption wasn't just suboptimal — it was actively working against the use case.
"Longer documents" was a real stakeholder objection. The 30% task completion delta killed it. You can't argue against user performance data with cost estimates.
Three layouts. 12 developers. Timed tasks. Readable won — despite longer documents.
The data settled the density question. Three other decisions still needed to be made explicitly — each with a real alternative that was rejected.
The accessibility decision was the most contested
Full system redesign on accessibility was the hardest call — and engineering pushed back hard.
The alternative: fix the most visible failures, call it done. I rejected it.
Partial compliance is a trap — fix the obvious failures and the next audit finds what you didn't fix. More practically: if compliance isn't in the typography tokens, it requires manual review of every document at publication. That's not a system. Full redesign now meant no regression later.
Engineering pushed back. I held the position. WCAG 2.1 AA achieved on first pass. No remediation cycles.
The solution
A design system for documentation — not a redesigned page
The deliverable was never a page. It was rules — a system that produces correct, accessible, readable documents automatically, across every service, every guide, every language.
Each improvement mapped directly to a failure from the original audit.
1: Heading hierarchy — clear H1/H2/H3 typographic scale
2: Asset parity to web — consistent with Cloudscape documentation
3: Code block clarity — improved readability, handled long lines
4: Navigation visual anchors — page landmarks for fast scanning
Same content. Different system. The difference is legibility under pressure.
Impact
The redesign was validated through usability testing with 12 developers in timed implementation tasks, comparing the original system against the redesigned one.
WCAG 2.1 AA
Compliance achieved, first time in platform history
30% Faster
Information discovery (usability testing, n=12)
200,000+
PDFs improved (programmatic, not manual)
Developer workflow
Documentation repositioned as product surface
What 30% actually means
A 30% reduction in time-to-information on a timed implementation task — finding a specific code parameter under pressure — is not a UX improvement at AWS's scale. It's a developer productivity improvement. At millions of sessions per month, that compounds into real time recovered. That's the framing that matters.
Reflection
The reframe was necessary — I'd do it the same way.
Without positioning this as a workflow improvement, it's a visual refresh that gets scoped to cosmetics. The frame determined what the project was allowed to be.
I under-solved for offline.
The redesign improved readability. It didn't rethink how developers use PDFs offline — as persistent references they annotate, share, and revisit over months. The interactive capabilities (navigation trees, internal links) were improved but not rebuilt from a use-case-first perspective. That's the version I'd want to design next.
The question this project left open:
The more interesting question isn't how to improve documents — it's what replaces them. Developers' actual need is getting unblocked fast with correct information in context. IDE integrations, AI assistants, contextual help surfaces are already better at that than a PDF. The redesign was the right investment for 2023. I'm less sure PDFs are the right investment for 2026.
