8. Project: Design Doc in Plain English

Description

We've reached the end of the module, and this is the point where everything you've seen stops being theory. You're going to write a complete design document in English about a real system — yours, or from the ecosystem you're studying — with goals, non-goals, alternatives, and risks, plus an ADR recording the central decision and the associated repository's README. This isn't an exercise to turn in and forget: it's a piece you can put in your portfolio, link on your profile, or show in an interview when someone asks "tell me about something you designed."

I know what you might be thinking: "my written English isn't good enough for a design document." Here's the good news, and it's this project's heart. Plain English — the kind this module taught — favors non-native speakers. Short sentences get written with fewer mistakes. Common vocabulary trips you up less than convoluted vocabulary. A native speaker writing "we should leverage this to facilitate the utilization of..." is writing worse than you writing "we use this to..." The criterion this project gets measured against isn't your grammar: it's whether an outside reader understands the problem. And that you can achieve today.

Connection to the module: the previous seven lessons were loose pieces — why plain language wins, the design doc's anatomy, how to explain architecture, the ADR, the README, and the blameless postmortem. This lesson brings them together into a single deliverable and adds a measurable quality gate: the outside-reader test. The postmortem from lesson 7 is deliberately left out of this deliverable — that gets written when something fails, not when something gets designed; here the focus is the writing that precedes building, not the writing that follows an incident. It's also the last lesson before the guide moves into spoken English, and that's not a coincidence: in a design meeting or an interview panel you're going to explain exactly this document out loud. Having it written and organized is what saves you when the language gets expensive.

What you're going to deliver

The project is three artifacts, not one. Each one serves a different function, and together they tell the complete story of an engineering decision.

The rule tying them together: the same problem, told three times at three levels of detail. The design doc explores it, the ADR freezes it into a decision, the README tells you how to run the result. If the three don't talk about the same system, something's wrong.

What to expect on time: a serious first draft is going to take you between 3 and 5 hours split across two sessions. Don't do it in one sitting. Write the design doc, sleep, and the next day reread it with outside-reader eyes before pulling out the ADR and the README. The draft you write tired is the one that sounds convoluted.

Step 1: pick the system (and keep it small)

This project's number-one mistake is picking a system that's too big. "Design Netflix" doesn't fit in three pages and is going to sink you. What you're after is a system with exactly one interesting decision you can defend.

Good candidates:

• A component you already built in another guide or bootcamp (a data pipeline, an API, a cache).
• Part of a real project from your work, anonymized.
• An honest redesign: "I have this working as X, I want to justify why I'd move it to Y."

The right-size test: you must be able to name the alternative you rejected in a single sentence. If there's no clear alternative, there's no decision to document, and with no decision, the design doc has no backbone.

Example of a properly sized system, written as you'd put it at the start of the doc:

"A background job that ingests daily CSV exports from a partner, validates them, and loads them into our reporting database. Today it runs as a single script triggered by cron; this doc proposes moving it to a queue-based worker."

It's all there: what it does, how it works today, and what you're proposing to change. A crystal-clear alternative (cron script vs. queue worker). That fits in three pages and can be defended.

Step 2: the design doc, section by section

Use this structure. The headings go in English because that's how you'll see them on any real team. Below each one I give you an English template so you can start without staring at a blank page.

Title, author, status

# Design: Queue-based CSV ingestion
Author: <your name> · Date: 2026-07-19 · Status: Draft

Status is a living field: Draft → In review → Accepted → Implemented. Never delete an old one; strike it through or move it.

Context / Background

Here you explain the problem before proposing anything. A reader who wasn't in the conversation has to understand why this exists.

Template in English:

"Today, X works like this: ... This causes the following problem: ... We need to change it because ..."

Golden rule: if your context section doesn't mention a concrete pain (something crashes, something's slow, something's costly, someone wastes time), you don't have a problem, you have a whim. Name it.

Goals

A short list, with concrete verbs and, when you can, a number.

Goals:
- Process a failed file without losing the whole batch.
- Retry a failed load automatically up to 3 times.
- Keep total ingestion time under 10 minutes for a 1 GB file.

Non-goals

This is the section separating a junior from someone senior, and almost nobody writes it. Non-goals explicitly say what you're not going to solve, so nobody assumes you covered it. They protect you and clarify the scope.

Non-goals:
- Real-time ingestion. This design stays batch/daily.
- Changing the partner's file format. We take the CSV as given.
- Historical backfill of old files. Out of scope for this doc.

What to expect: when someone reviews your doc, half the uncomfortable questions ("what about X?") disappear if X is listed as a non-goal. Writing three honest non-goals is worth more than a page of explanations.

Design / Proposed solution

Here you describe the solution. Short sentences, one paragraph per piece. If you need a diagram, an ASCII diagram or a numbered list of steps is worth more than a pretty drawing you can't edit.

"A worker pulls file names from a queue. For each file, it: (1) validates the header, (2) loads rows in batches of 500, (3) marks the file as done or failed. Failed files go back to a retry queue with a delay."

Alternatives considered

The document's pillar. For every alternative: what it was, and why you didn't choose it. Without the "why not," it's not an alternative, it's decoration.

Alternatives considered:

1. Keep the single cron script.
   Rejected: one bad row fails the whole file, and we cannot retry
   without re-running everything by hand.

2. Use a managed ETL service (e.g. a hosted pipeline tool).
   Rejected: adds a paid dependency and a vendor lock-in for a job
   that runs once a day. Too much for the size of the problem.

Risks and mitigations

Every design has edges. Naming them makes you look more senior, not less. For every risk, a mitigation.

Risks:
- The queue could pile up if the worker crashes.
  Mitigation: alert when queue depth > 100.
- A malformed file could poison the retry queue forever.
  Mitigation: move to a dead-letter queue after 3 failed retries.

Open questions

What you still don't know. Writing it isn't weakness; it's honesty, and it gives the reviewer an exact place to help you.

"Open question: should the retry delay be fixed (5 min) or exponential? Leaning fixed for simplicity — feedback welcome."

Step 3: the central decision's ADR

The design doc explores. The ADR freezes. Out of the whole document comes a single decision that deserves to be recorded forever, and that goes into an Architecture Decision Record with the classic four-field format.

# ADR 001: Use a queue-based worker for CSV ingestion

## Status
Accepted

## Context
The cron script fails the whole file on a single bad row and cannot
retry without manual re-runs. As volume grows, manual recovery does
not scale.

## Decision
We will process files through a queue-based worker. Each file is a
message; failures go to a retry queue, then to a dead-letter queue
after 3 attempts.

## Consequences
Positive: partial failures no longer block the batch; retries are
automatic; the worker scales horizontally.
Negative: we add a queue as new infrastructure to run and monitor.

Three things that set an ADR apart from a design doc, and that are worth having clear because they get mixed up all the time:

• The ADR is immutable. You don't edit it when you change your mind: you write a new ADR that says "supersedes ADR 001" and mark the old one as Superseded. The decision history is the value.
• The ADR doesn't argue, it declares. The full "why" lives in the design doc; the ADR keeps the summary a future maintainer needs in 30 seconds.
• Consequences includes the negative. An ADR that only lists advantages is lying. The negative section is what makes the reader believe you.

Step 4: the repository's README

The README is the first thing whoever lands on your code sees, and often the only thing. Its job is getting a stranger from "I don't know what this is" to "I have it running" with no questions to you.

Skeleton in English, in the order people actually read it:

# CSV Ingestion Worker

One line: what it does and who it is for.
> Ingests daily partner CSVs into the reporting database, with retries.

## Why it exists
Two sentences on the problem. Link to the design doc.

## Requirements
- Python 3.12+
- A running queue (see config below)

## Quickstart
    git clone <repo>
    make install
    make run

## Configuration
| Env var        | What it does                 | Default |
|----------------|------------------------------|---------|
| QUEUE_URL      | Where to read file names     | —       |
| MAX_RETRIES    | Attempts before dead-letter  | 3       |

## Links
- Design doc: ./docs/design.md
- Decision record: ./docs/adr/001-queue-worker.md

The README rule: the Quickstart goes on top, not at the bottom. Whoever arrives wants to run it, not read your philosophy. And the command block has to work copied exactly as-is; a command that fails on the first line destroys all trust in the rest of the document.

Step 5: self-review with the plain-language rubric

Before showing it to anyone, run your own text through the module's rubric. This is what's going to raise the quality the most and, paradoxically, what's most reassuring if you feel your English isn't enough: it's almost entirely about removing, not writing better.

Replacement table. Find the left column in your text and swap it for the right one:

Self-review checklist. Read it with your finger on each point:

• Split long sentences. If a sentence goes past two lines or has three commas, cut it into two. The period is your best friend and the one that lets you make the fewest grammar mistakes.
• Active voice. "The worker loads the rows" beats "the rows are loaded by the worker." Active is shorter and clearer, and a non-native speaker makes fewer mistakes with it.
• One acronym, one definition. The first time DLQ shows up, write "dead-letter queue (DLQ)." After that, use DLQ.
• Every alternative has its "why not." If one has no explicit rejection, either justify it or delete it.
• The non-goals exist. At least two. If you can't find any, you didn't think through the scope well.
• Zero smoke adjectives. robust, seamless, powerful, cutting-edge. They prove nothing and sound like a brochure. Delete them.

What to expect: applying the table and checklist, your document is going to shrink by 15% to 30%. That's success, not loss. What's left is easier to read and, for you, easier to have written well.

Step 6: the outside-reader test (the acceptance criterion)

Here's the project's quality gate, and it's the only grade that matters. Your document does not get evaluated by your grammar or your vocabulary. It gets evaluated by someone else's comprehension. The criterion is concrete:

Someone who doesn't know your project should be able to explain, in their own words: (1) what problem it solves, (2) which alternative you rejected, and (3) why.

How to run the test:

1. Hand your design doc to someone — a coworker, a bootcamp friend, even someone from another field. They don't need to be a native English speaker or an expert in your domain.

2. Don't explain anything out loud. The point is for the document to speak on its own. If you have to clarify something by talking, that something is missing from the document.

3. After reading, ask them exactly these three questions:

   • "In your own words, what problem does this solve?"
   • "Which alternative did I reject?"
   • "Why did I reject it?"

4. If they answer correctly, you passed. If they hesitate on any of them, don't argue: that section is weak. Go back to the document and fix it. The reader is never wrong; the document is what wasn't clear.

A trick if you don't have anyone on hand right now: read it out loud yourself, in English, as if you were explaining it to someone. This is also the perfect rehearsal for the spoken English coming up in the next module. The places where your own voice stumbles or tangles are almost always the places where the text is tangled. Mark those sentences and rewrite them shorter.

Common mistakes (and how to avoid them)

Exercises

These exercises get you to operate the project's pieces separately — scoping a system, writing non-goals, applying the plain-language table, designing the outside-reader test — before you bring all three together into your own design doc. Work through each one with a pencil before opening the solution.

Exercise 1 — Find the alternative in one sentence

You have this system in mind: "I want to redesign how my team deploys the backend." It's too big for a 1–3 page design doc. Trim it down to a system with exactly one defensible decision, and write the alternative that would summarize the change in "X vs. Y" format.

Exercise 2 — Write the non-goals

System: a worker that syncs an online store's inventory every 15 minutes by reading a CSV a supplier uploads. Write at least two honest non-goals for this design, in English, following the lesson's format.

Non-goals:
- Real-time inventory sync. This design stays on a 15-minute schedule.
- Validating the CSV's business logic (e.g. duplicate SKUs across
  files). We only validate structure, not content correctness.

Exercise 3 — Apply the replacement table

Rewrite this paragraph using the lesson's plain-language table:

"In order to facilitate the utilization of the new pipeline, it is recommended that you leverage the existing configuration prior to making any changes, due to the fact that a large number of services depend on it."

Exercise 4 — Design the outside-reader test

You wrote the lesson's example design doc (moving from "cron script" to "queue-based worker"). Write the exact three questions you'd ask your test reader, and describe an answer that would tell you the "Alternatives considered" section is weak.

Submission and module close

Your final deliverable is a folder with three files:

/design.md          -> the complete design doc
/adr/001-<slug>.md  -> the central decision's ADR
/README.md          -> the repository's README

And one condition: that an outside person has passed the outside-reader test by answering the three questions. Note down, in one line at the end of the design doc, who read it and what they answered; that note is your evidence that the document works, not just that it exists.

With this you close out the technical writing module. It's worth saying out loud what you just accomplished, because it's bigger than it looks: you produced, in English, the hardest-to-fake seniority evidence there is, one that needs nobody's permission. You didn't demonstrate you can execute tasks — anyone can do that — you demonstrated you can hold up a decision in writing in front of readers who weren't in the room. That's exactly the signal the postings the research audit flagged were asking for with "written architecture communication" and "design document in plain language."

And if linguistic impostor syndrome is still hanging around, hold on to this: the document you wrote didn't win because of your English, it won despite your English not being perfect — because plain language doesn't reward whoever knows more words, it rewards whoever makes themselves understood. That field is level for you. In the next module you're going to take exactly this document and learn to defend it while speaking; you arrive with the hard part — having something clear to say — already solved.

Summary and next step

In this lesson you brought the module's previous seven lessons together into a single deliverable with three artifacts — design doc, ADR, and README — that tell the same engineering decision at three levels of detail, and you gave it a measurable quality gate: the outside-reader test.

Before moving on to the next module, you should be able to:

• Scope a system down until it fits in 1–3 pages and name, in one sentence, the alternative you rejected.
• Write the design doc's sections in plain English, with at least two honest non-goals and every alternative carrying its "why not."
• Draft a four-field ADR that declares the decision without arguing it, including one real negative consequence.
• Write a README with the Quickstart on top and commands that work copied exactly as-is.
• Run your own text through the replacement table and the plain-language checklist, and watch the document shrink with no loss of meaning.
• Run the outside-reader test with a real person and log their answer to the three questions.

If any of these points still trips you up, go back to the corresponding step before closing out the module: the document that comes out of here is the one you're going to defend by speaking in the next module, and a written crack shows even more out loud.

The bridge: in module 5 — spoken English — you're going to take exactly this design doc and learn to explain it in a design meeting and defend it against live questions, with none of the safety net of deleting and correcting you had here. You arrive with the hardest part already solved: having something clear to say. What follows is learning to say it.

Resources

• Design Docs at Google — the reference article on how Google uses design docs before writing code; its sectioned anatomy (context, goals, non-goals, alternatives) is the same one this lesson follows.
• Architecture Decision Records (adr.github.io) — the ADR community's site, with templates and tools for writing and organizing your own decision records.
• Documenting Architecture Decisions — Michael Nygard — the original post proposing the four-field format (Status, Context, Decision, Consequences) this lesson's ADR uses.
• Make a README — a practical guide on what a README should contain and in what order, with the same "someone should be able to run it with no questions to you" criterion.
• Plain Language Guidelines (digital.gov) — the US government's official plain-language writing guidelines; the foundation behind this lesson's replacement table and self-review checklist.