Capstone Project C — The Documentation Sprint

A focused capstone for the Software/CS track (and anyone documenting a technical system). Fully document one real or sample project: a README, a reference doc, a tutorial, an Architecture Decision Record, and a troubleshooting section — the complete documentation set a developer meets when they land on your project cold.

Which capstone is this? One of three briefs in this part, all graded by capstone-rubric.md. This one is the deepest dive into developer-facing writing, drawing on Chapters 22, 24, 25, 26, and 34. Choose it if your work lives in code and your readers are users and maintainers. For the broad version, see the Portfolio (capstone-project-portfolio.md); for the audience-translation version, see the Translation Challenge (capstone-project-translation.md).

Purpose

Documentation is not the thing you do after the code works. It is what decides whether the code gets used at all. A brilliant tool with a wall-of-text README dies unused; an ordinary tool with an excellent quick-start gets adopted. Raj Patel learned this across Chapters 24–26: the README is the front door, and most front doors are locked.

In this capstone you document one project end to end, producing the five document types a real software project needs. The discipline that ties them together is Diátaxis (Chapter 26): a piece of documentation is one of four kinds — a tutorial, a how-to, a reference, or an explanation — and the silent cause of most bad docs is mixing them. A page trying to be a tutorial and a reference and an explanation is too slow for the expert and too overwhelming for the beginner. Your job is to know which kind each document is, and build each for its one reader's situation.

The Project

Pick a project to document. Three good options, in order of how much they prove:

1. A real project you've built — a script, a library, a CLI tool, a small web app, a data pipeline. This is the strongest choice: real documentation for real code is the most convincing thing in a portfolio.
2. A real open-source project with weak docs — fork it (in the documentation sense) and rewrite its docs. The "before" is real and the improvement is visible. Cite the original honestly; don't claim authorship of the code.
3. A provided sample project — a small, well-scoped fictional tool (a sample CLI, a sample API) that your instructor or you define in a paragraph. Label it clearly as a sample. Fine for practice, though it proves less than documenting real code.

State the project in a paragraph at the top: what it does, who uses it, and what someone needs to install or run it. Everything downstream serves a reader who lands on this project knowing nothing.

The Five Deliverables

Each maps to a Diátaxis mode (or a software genre from Chapter 25/34). Name the mode of each document in a one-line note — if you can't name the mode, the document doesn't yet know what it is.

1. A README — the front door (reference-oriented landing page). The single most important document; most readers never go further. Cover, in roughly this order (Chapter 25): what it does (does it solve my problem?), installation (how do I get it?), quick-start / usage (show me it working — the most important part, and a runnable example beats a paragraph), a pointer to fuller docs, contributing, and license. The metric for the quick-start is time-to-first-success: how fast can a reader get a working result? Lead with that. A scanning reader (Chapter 4) should answer "is this for me, and how do I start?" in thirty seconds.

2. An API / reference document (reference mode). The document a developer consults to use your code without reading its source (Chapter 25). For each function, endpoint, command, or configuration option: what it does, its parameters/arguments (types, required vs. optional, defaults), what it returns, the errors or status codes it can produce, and a short runnable example. Reference docs are information-oriented and complete — the reader arrives knowing what they want and needs to find it fast, not be taught. Consistency of structure across entries is the whole game; a reader who learns one entry's shape can read them all.

3. A tutorial (tutorial mode — Diátaxis). One concrete goal stated up front; a single tested path with no forks; every step shown literally with the expected result after each step so the beginner can confirm "did that work?"; minimal explanation at the moment of use; a guaranteed-clean starting environment; and a named win at the end (Chapter 26). Walk the happy path only — defer edge cases to how-tos. The defining property: a tutorial guarantees success. The threshold concept from Chapter 26 is exactly this — a tutorial guarantees success; a how-to assumes it — and your tutorial must be tested on a fresh environment or, better, a real beginner. If it has only ever worked for you, you don't know that it works; you know it works for a sample size of one.

4. An Architecture Decision Record (explanation mode). A single ADR (Chapter 25) capturing one real design decision — why you chose this database, this framework, this data format. Use the format popularized by Michael Nygard: Context (the forces and constraints at the time), Decision (what you chose), and Consequences (what follows, good and bad), often with a Status. Keep it to a page or less — the tiny format is what makes writing one cheap enough to actually do. The ADR captures the why a future maintainer would otherwise have to reverse-engineer.

5. A troubleshooting section (how-to mode). The problems a real user hits, and the fix for each (Chapter 22, Chapter 26). Structure it as symptom → cause → fix, indexed by the symptom the reader actually observes ("ImportError: No module named requests"), not by your mental model of the system — because the reader searches for what they see, not for what's wrong underneath. This is the document that turns a frustrated user into a successful one without a support ticket. A how-to assumes competence and solves a specific problem, which is what makes it different from the tutorial.

Constraints and Honesty

• Test the tutorial. The one hard, checkable requirement. Run it in a brand-new clean environment, or hand it to someone who has never done the task, and fix every place they stall. Note in your reflection where it broke — the gap you couldn't see is the curse of knowledge (Chapter 2) in action.
• Attribute honestly. If you documented someone else's open-source code, say so and link the original; you claim the documentation, not the code. If the project is a fictional sample, label it.
• No invented behavior, and runnable examples must run. Document what the code actually does, not what you wish it did — a reference doc describing a parameter the code ignores sends the reader down a path that fails (Chapter 38). A quick-start example that errors on paste is the fastest way to lose a developer's trust.

Deliverables Summary

Submit one documentation set (a folder, a small site, or a single structured document) containing, in order:

1. The project description (one paragraph) and a one-line mode label for each of the five documents (tutorial / how-to / reference / explanation).
2. The five documents: README, API/reference doc, tutorial, ADR, troubleshooting section.
3. A short reflection (~300–400 words): Which document was hardest to keep in a single mode, and what did you have to split out? Where did testing the tutorial reveal a gap you couldn't see? What "why" did the ADR capture that would otherwise have been lost? The reflection is assessed for the Diátaxis judgment it shows.

Evaluation

Graded with capstone-rubric.md. Two dimensions carry extra weight here: structure (did you keep each document in a single Diátaxis mode?) and accuracy/citation honesty (does the documentation match what the code does, and is borrowed code attributed?). Brief-specific markers:

The test the whole capstone reduces to: a developer who has never seen your project can install it, get it working, look up what they need, understand one key decision, and fix a common problem — using only the documents you wrote, with no access to you. That is what good documentation is: the author, made unnecessary. Build the set so the reader never has to ask you anything.