Stop Shipping Slide Decks

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:

1. the 40-page slide deck
2. 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]

Contents

• 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

1. RFC-lite (1-2 pages): the “what” and “why”
2. 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