Stop Shipping Slide Decks

Sat, 31 Jan 2026 11:15:00 -0500

Position: This is not “documentation bad.” This is “documentation is a tool.” If it increases lead time, hides truth, or replaces learning, it’s not helping.

Why this matters

In software, the real “source of truth” is:

running systems
code and configuration
production telemetry
incident history

Documentation should reduce uncertainty and speed up decisions. But two artifacts routinely do the opposite in large organizations:

the 40-page slide deck
the Word doc living somewhere in SharePoint that nobody can find

These artifacts often become deliverables - a substitute for building. They make it possible to spend months “progressing” without ever encountering reality.

And here’s the part most orgs miss:

If you’re going to fail, you want to fail quickly and cheaply, not slowly and expensively. [4]

That doesn’t mean reckless shipping. It means running a tight learning loop and letting reality correct you early - before you’ve sunk quarters of time into the wrong solution.

TL;DR

Decks are great for storytelling. They are bad as an engineering system of record.
“SharePoint architecture docs” become a document cemetery: hard to find, hard to diff, and easy to ignore.
The Agile Manifesto explicitly values working software over comprehensive documentation. [1] And one Agile principle states that working software is the primary measure of progress. [2]
Replace decks/docs-as-deliverables with:
RFC-lite (1-2 pages) + a running thin slice
ADRs (Architecture Decision Records) to capture decisions + tradeoffs [5][6]
Docs-as-code (Markdown in the repo, reviewed like code)
diagrams that are versioned and easy to update
Measure improvement with system outcomes (lead time, deploy frequency, change failure rate, MTTR). [3]

Pattern 1: Deck-driven development
Pattern 2: SharePoint document cemeteries
Pattern 3: Architecture as narrative, not decisions
Pattern 4: “Design phase” gating
Pattern 5: Documentation that never gets pruned
What to do instead: a documentation system that ships
Verification: how you know it’s working
A practical checklist
References

Pattern 1: Deck-driven development

What it looks like

A 40-page deck is created to describe a system that doesn’t exist yet.
The deck gets reviewed by multiple groups.
Approval is treated as progress.
When implementation starts, the world has changed - or key constraints were missed.

Why it exists

Decks are socially useful:

they compress complexity into a narrative
they help leaders “see” a plan
they make uncertainty feel controlled

The hidden tax

Decks are a poor engineering artifact because they’re:

low fidelity: they rarely contain executable truth
hard to maintain: updates are manual and usually lag reality
hard to diff: you can’t easily review what changed and why
easy to perform: a deck can look complete while the design is still untested
not tied to code: no direct path from “decision” -> “implementation” -> “verification”

The worst outcome isn’t that the deck is wrong. It’s that the deck delays the point where you discover what’s wrong.

The replacement pattern

Use decks for storytelling after you have reality. Use engineering artifacts to discover reality.

A strong default:

RFC-lite (1-2 pages)
a runnable thin slice
measurable verification (latency, cost envelope, failure mode)

This aligns with Agile’s emphasis on working software as a real measure of progress. [2]

Transition step (low drama)

Replace “deck required for approval” with “evidence required for approval”:

link to the RFC
link to a running demo / branch / sandbox
explicit constraints + tradeoffs
an exit criteria checklist for the slice

Pattern 2: SharePoint document cemeteries

What it looks like

Architecture docs exist as Word/PDF files in SharePoint.
Multiple versions exist (“Final_v7_REAL_FINAL.docx”).
Search works poorly unless you already know what to search for.
Nobody updates the doc because it’s painful and risky (“what if I change the blessed doc?”).

Why it exists

It’s an enterprise default:

SharePoint is “official”
Word docs feel formal
it’s familiar to non-engineering stakeholders

The hidden tax

SharePoint docs typically fail at the things engineering needs most:

discoverability (people don’t know where to look)
ownership (no clear maintainer)
reviewability (diffs and PR discussion are weak)
linking to reality (code, configs, dashboards, runbooks)
keeping current (documentation drift becomes the norm)

So teams stop trusting docs and rely on tribal knowledge - until they page someone at 2 a.m.

The replacement pattern

Treat documentation as part of the codebase:

Markdown in the repo
reviewed via PR like code
versioned with implementation
linked to:
APIs (OpenAPI specs)
dashboards
runbooks
incident writeups
ADRs

Google’s documentation best practices make the point directly: a small set of fresh, accurate docs is better than a large pile in disrepair. [7]

Transition step

You don’t have to “migrate all docs.”

Start with a triage:

Identify the top 10 documents people actually need.
Recreate them as Markdown in a docs/ folder with an index.
Leave the rest as archived references, not living truth.

Pattern 3: Architecture as narrative, not decisions

What it looks like

The doc describes a target architecture but doesn’t answer:

why this approach?
what alternatives were considered?
what tradeoffs were accepted?
what constraints matter most?
what did we decide not to do?

Why it exists

Narratives are easier than decision logs. It’s simpler to write “the system will…” than to record the messy reality of tradeoffs.

The hidden tax

When decisions aren’t recorded, teams re-litigate them repeatedly. The same arguments come back every quarter - often because new people joined and the reasoning isn’t captured.

The replacement pattern: ADRs

Use Architecture Decision Records (ADRs): short, structured notes that capture an important decision with its context and consequences. [5] The practice is commonly attributed to Michael Nygard’s 2011 write-up. [6]

ADRs are the opposite of a 40-slide deck:

small
specific
diffable
linkable to code changes

Transition step

Start with one ADR per “architecturally significant decision”:

database choice
messaging pattern
tenancy model
auth model
deployment model
data boundary decisions

Pattern 4: “Design phase” gating

What it looks like

“We can’t start implementation until the analysis is complete.”
The analysis expands to include every possible future case.
The design grows more “complete” and less true.

Why it exists

Enterprises are understandably afraid of failure.

The hidden tax

This approach doesn’t eliminate failure. It defers it - making it more expensive.

Lean Startup describes progress as validated learning and emphasizes moving quickly through a build-measure-learn loop. [4] The point isn’t startups. The point is learning fast when you’re uncertain.

The replacement pattern

Timebox design, then validate with a thin slice:

write the RFC-lite doc
implement the smallest realistic end-to-end path
measure the constraints
then expand

Transition step

Define “analysis exit criteria”:

measurable constraints validated (not theorized)
spike code exists
a plan for incremental rollout exists

Pattern 5: Documentation that never gets pruned

What it looks like

Docs accumulate but aren’t maintained:

outdated architecture diagrams
old runbooks
stale onboarding guides
dead links

Why it exists

Pruning isn’t rewarded. Writing new docs feels productive; deleting old docs feels risky.

The hidden tax

Stale docs are worse than no docs:

they mislead
they increase cognitive load
they create false confidence

The replacement pattern

Adopt “minimum viable documentation” and prune regularly. [7]

The rule I like:

If a doc isn’t maintained, label it ARCHIVED and explain why.
If a doc is required, tie it to ownership and change workflow.

Transition step

Make docs part of PR hygiene:

if the change affects behavior, docs update ships with it
run link checks in CI
keep an index page updated

What to do instead: a documentation system that ships

Here’s a simple “docs system” that works in practice.

A repo structure that scales

/README.md # entry point: what this is + how to run it
/docs/
 index.md # "start here" documentation map
 rfc/
 0001-tenancy-model.md
 0002-storage-approach.md
 adr/
 0001-use-postgres.md
 0002-adopt-opentelemetry.md
 architecture/
 context.md # C4-ish: context + boundaries
 containers.md # top-level services
 deployment.md # runtime & environments
 runbooks/
 oncall.md
 incident-response.md
 api/
 openapi.yaml

Replace 40 slides with two artifacts

RFC-lite (1-2 pages): the “what” and “why”
Thin slice demo: the reality check

RFC-lite template (copy/paste)

# RFC: <title>

## Problem
What are we trying to solve? Who is affected?

## Constraints
Latency, cost, compliance, tenancy, uptime, environments.

## Proposal
What are we building? What does "done" mean?

## Alternatives considered
Option A / B / C with short tradeoffs.

## Risks and mitigations
What could go wrong? How will we contain blast radius?

## Verification
How will we measure success in production?

ADR template (copy/paste)

# ADR-XXXX: <decision>

## Status
Proposed | Accepted | Deprecated

## Context
What drove this decision? What constraints matter?

## Decision
What did we decide?

## Consequences
What do we gain? What do we lose? What changes later?

Verification: how you know it’s working

If you replace decks and doc cemeteries with real engineering artifacts, you should see:

Delivery metrics improve

Track the same system-level outcomes DORA promotes: lead time, deploy frequency, change failure rate, and time to restore service. [3]

Fewer handoffs and fewer “alignment meetings”

If teams can self-serve context from living docs, coordination cost drops.

Faster “first reality”

A simple heuristic:

How long from idea -> first runnable thin slice?

If that number is months, the system is optimized for analysis, not learning.

Docs stay alive

docs updated alongside code
fewer stale “final_v7” files
fewer tribal-knowledge escalations

A practical checklist

If you want to kill deck-driven delivery without starting a culture war:

Stop treating decks as deliverables

Architecture reviews require an RFC + a runnable slice.
Decks are optional; evidence is not.

Fix document discoverability

One docs/index.md that links to the docs that matter.
Make the repo the source of truth for technical docs.

Capture decisions, not fantasies

Add ADRs for major decisions and link them to PRs. [5][6]

Timebox analysis

Set analysis exit criteria.
Optimize for early learning and quick failure when uncertainty is high. [4]

Keep docs small and alive

Prune regularly; archive what’s stale.
Run link checks in CI.
Treat docs like bonsai: maintained and trimmed, not accumulated. [7]

References

[1] Manifesto for Agile Software Development (values; “Working software over comprehensive documentation”). https://agilemanifesto.org/ [2] Principles behind the Agile Manifesto (“Working software is the primary measure of progress”). https://agilemanifesto.org/principles.html [3] DORA - “DORA’s software delivery performance metrics (guide)”. https://dora.dev/guides/dora-metrics/ [4] Lean Startup principles (Build-Measure-Learn; learning quickly; failing fast/cheaply as a concept). https://theleanstartup.com/principles [5] ADR - Architectural Decision Records (what ADRs are). https://adr.github.io/ [6] Michael Nygard - “Documenting Architecture Decisions” (2011; ADR practice origin/popularization). https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions [7] Google Documentation Guide - Best practices (“Minimum Viable Documentation”; keep docs short, fresh, and pruned). https://google.github.io/styleguide/docguide/best_practices.html

Documentation | Roy Gabriel

Stop Shipping Slide Decks

Why this matters

TL;DR

Contents

Pattern 1: Deck-driven development

What it looks like

Why it exists

The hidden tax

The replacement pattern

Transition step (low drama)

Pattern 2: SharePoint document cemeteries

What it looks like

Why it exists

The hidden tax

The replacement pattern

Transition step

Pattern 3: Architecture as narrative, not decisions

What it looks like

Why it exists

The hidden tax

The replacement pattern: ADRs

Transition step

Pattern 4: “Design phase” gating

What it looks like

Why it exists

The hidden tax

The replacement pattern

Transition step

Pattern 5: Documentation that never gets pruned

What it looks like

Why it exists

The hidden tax

The replacement pattern

Transition step

What to do instead: a documentation system that ships

A repo structure that scales

Replace 40 slides with two artifacts

RFC-lite template (copy/paste)

ADR template (copy/paste)

Verification: how you know it’s working

Delivery metrics improve

Fewer handoffs and fewer “alignment meetings”

Faster “first reality”

Docs stay alive

A practical checklist

Stop treating decks as deliverables

Fix document discoverability

Capture decisions, not fantasies

Timebox analysis

Keep docs small and alive

References