Skip to main content

Per-Project One-Pagers

What This Concept Is​

A per-project one-pager is the top of every README. It is the answer a reader sees before they scroll. The goal is: after 90 seconds, a reviewer can describe the project to someone else in their own words.

Three traits make a one-pager good:

  • Consistent -- every project follows the same structure, so a reviewer can navigate any repo without re-learning.
  • Scannable -- the first screen answers "what is this, why does it exist, does it work?" without scrolling.
  • Honest -- it states the real scope, including what is not implemented.

One-pagers are a house style, not a template you impose on each project individually. Once the shape is fixed, every new project inherits it for free and every reviewer who has read one of your repos can read the next one at roughly twice the speed.

The one-pager is also the scaffold on which all other artifacts hang. The profile README (concept 04) points at it. The case study (cluster 1) extends it. The blog posts (concept 08) frequently start as an expanded version of the "Why It Exists" section. Treating the one-pager as a primitive pays out across the portfolio.

Why It Matters Here (In the Capstone)​

Reviewers do not read READMEs linearly; they land, scan, and bail if the first screen is unclear. A consistent one-pager structure across all your pinned repos compounds: the reviewer learns to read your work faster each time.

Inconsistency also leaks information. If one README is polished and another is a scratchpad, the reviewer cannot tell which represents you. The honest answer is usually "both," and that is the wrong answer.

For the capstone specifically, the one-pager is the default reading path for any reviewer who is not ready to commit to the full case study. A weak one-pager traps the case study behind a bad first impression; a strong one-pager invites the reviewer to keep reading.

Concrete Example: One-Pager Template​

Every project README starts with these sections, in this order:

# <project name>

**One-line summary (<= 25 words):**
<what this is, for whom, doing what>

**Status:** <production / working demo / exploratory / archived>
**Primary author:** <you> - **Period:** <YYYY-MM to YYYY-MM>

## Why It Exists

<2-3 sentences. The problem, not the technology.>

## What It Does

<3-5 bullet points or one short paragraph. Observable behavior,
not implementation.>

## Architecture (one diagram)

<mermaid or image, labeled, <= 8 nodes>

## Running It

<5-10 lines of commands, copy-pasteable. No surprises.>

## What Is and Is Not Implemented

- Done: <list>
- Known gaps: <list>
- Deliberately out of scope: <list>

## Where to Look First

- `src/<file>` -- <why>
- `library/raw/case-study.md` -- the narrative
- `adr/` -- design decisions

That structure fits on one scroll in most clones. Any project longer than the above should link out to a library/raw/ folder, not grow the README.

Concrete Example: Honest "What Is Not Implemented"​

Bad:

"Fully production-ready distributed inventory system."

Reviewer: "Really? At what scale? With what operator support?" If pressed, the claim collapses.

Good:

"Handles ~50 rps sustained on a single node with a 24-hour dedupe window. Multi-region replication is out of scope. No authn/authz implemented -- designed to sit behind an internal gateway. Failover has been rehearsed locally but not run in staging."

The good version would survive a hostile reading. It also invites the right follow-up questions.

Concrete Example: The Consistency Dividend​

Consider two candidates who each have three pinned repos.

Candidate A has three distinct README styles: one template-driven, one ad-hoc, one half-empty. A reviewer opens the first, learns a structure, opens the second, has to relearn, opens the third, gives up. Evaluation time: ten minutes of friction, low confidence.

Candidate B uses the one-pager template across all three. The reviewer learns the structure once and reads each repo in two to three minutes. Evaluation time: eight minutes, high confidence. Same content, different packaging, dramatically different conclusion.

The template itself does not make either candidate smarter. It makes Candidate B legible, which matters more than being smart when the reviewer has twenty other profiles queued up.

Common Confusion / Misconceptions​

Thinking a one-pager is marketing. It is not. Marketing hides the scope. The one-pager's job is to set the right expectations so the deeper read rewards the reader. A reviewer who got surprised by what was missing downstream will trust you less; a reviewer who already knew what was out of scope can evaluate the rest fairly.

Believing the one-pager must be short. It must be scannable. Scannable means clear headings, short lists, no wall-of-text. 150-300 words on the first screen is fine if it is structured.

Writing the one-pager last. The one-pager is a design artifact, not a summary artifact. Writing it first -- before the project exists -- forces you to commit to the scope. Many capstone scope-creep disasters would have been prevented by an honest one-pager drafted at kickoff.

Decorative status badges. A build badge is useful if it is green and recent. A version badge on a non-versioned toy is noise. Badges earn their spot or they come out.

How To Use It (In Your Capstone)​

Once per project:

  1. Draft the one-line summary in <= 25 words. If it runs long, the project scope is unclear.
  2. Fill every section of the template.
  3. Do the honesty pass: "Is this what a reviewer will experience when they run it?"
  4. Do the consistency pass: do all your pinned repos use the same structure?
  5. Commit the template as library/raw/readme-template.md so future projects inherit it.
  6. Re-audit the "Status" line every quarter; a stale status is a specific credibility leak.
  7. Verify "Running It" actually runs -- ideally by cloning fresh into a scratch directory yourself.

Check Yourself​

  1. Can you state each pinned project in <= 25 words without looking?
  2. Does every pinned README disclose something that is not implemented?
  3. If a reviewer followed your "Running It" section, would it actually run?
  4. Do all pinned repos share the same one-pager structure?
  5. Has each pinned repo's Status line been reviewed in the last 90 days?
  6. If the one-pager were read aloud, would the listener be able to name the problem, the shape of the solution, and the scope boundary?

Mini Drill or Application (Capstone-scoped)​

Three drills:

  1. Rewrite the first screen. For your capstone repo, rewrite only the first screen of the README using the template above. Then close the file, wait ten minutes, come back, and read it cold. If you cannot summarize the project from the first screen alone, iterate.
  2. Fresh-clone drill. In a scratch directory, clone your capstone repo into /tmp/cold-clone. Follow the "Running It" section exactly, no memory, no shortcuts. Every friction point is a bug in the one-pager, not a bug in the reader.
  3. House-style pass. For each of your pinned repos, confirm the six section headings match. If even one uses different headings, the reader pays a re-learning cost. Align them.

Commit the final template as library/raw/readme-template.md under your capstone repo; future projects inherit for free.

Transfer / How This Synthesizes Prior Semesters​

The one-pager is a compression -- a very small surface that demands a lot of per-line work -- and the disciplines that make it work come from across the degree:

The single transferable move is the "explicit non-scope" bullet: in any artifact -- API, design doc, README, one-pager -- saying what is not in it is a cheaper form of defense than retrofitting the scope later.

See also (integrative)​

Source Backbone​

Portfolio assessment packages evidence from the whole curriculum. These books provide the technical and professional backbone for the narrative.