Writing up a project as a decision record

The ninety-second reading order

A reviewer opens your project page and reads in this order: the title, the first sentence, whatever number is visible, and then, if you have earned it, the section admitting what is wrong. They almost never read the code.

So write for that order. Everything that proves something goes above the fold, and the honest limitations go near the top rather than buried at the bottom, because their presence is itself the strongest signal on the page.

The template

# Bus delay tracker — Lagos, route 57

Tells a transport cooperative's dispatchers which departure
window runs late most often. Updated nightly.

**Used by** 6 dispatchers, weekly, since March 2026.

## The mess
Three of eleven months had GPS timestamps recorded in local
time and eight in UTC, with nothing labelling which. I found
it because "delays" spiked by exactly one hour on the day the
device firmware changed.

## Two decisions
- Dropped the first two weeks entirely rather than
  interpolating. The device swap meant I could not tell
  which clock any reading came from, and inventing a
  correction would have hidden that.
- Median rather than mean. Two breakdowns of four hours
  each were dragging every weekly average upward.

## Does it work
I wrote 30 test journeys with known outcomes from the
dispatchers' own paper log. It classifies 27 correctly.
Of the 3 misses, all are journeys crossing midnight.

## What it gets wrong
No handling of public holidays — a dispatcher found this
before I did. Midnight-crossing journeys, as above.

## Run it
`make dev`, then open localhost:8000. Sample data included.

That page takes ninety minutes to write and outperforms three more projects.

Why each section is there

The mess and how you found it. This is the only part of the page that cannot be faked by copying a tutorial. The detail that you noticed the spike was exactly one hour is worth more than any architecture description, because it shows how you think when something is wrong.

Two decisions, with the rejected alternative. A decision with no discarded option is not a decision. Naming what you did not do is what distinguishes judgement from following instructions.

A number. From the previous lesson. Thirty test cases and a count. Most beginner portfolios contain no number at all, and the ones that do stand out immediately.

What it gets wrong. Counter-intuitive and true: admitting a limitation raises your credibility on everything else on the page, because it tells the reader you know how to look for problems. A page with no limitations reads as a page written by someone who has not checked.

Publishing work you did for someone else

If the project was for a client or an employer, you cannot simply publish it.

• Ask, in writing, before you publish anything. An email saying “may I write publicly about the approach, with your name and figures removed?” is usually answered yes, and it protects you.
• Never publish their data. Not a sample, not an anonymised extract, not “just the schema” if the schema is distinctive.
• Replace real figures with realistic invented ones and say so. “Figures changed for confidentiality; proportions preserved” is honest and reviewers accept it.
• A blurred screenshot is not anonymisation. The underlying CSV may still be in your repository, and blur can sometimes be reversed. Regenerate the screenshot with fake data instead.
• If you cannot publish it at all, write a page about the problem shape with no client details. “How I found a timezone bug in a delivery dataset” needs no client name.

Show it moving

A forty-second screen recording of the thing working outperforms three paragraphs, because it proves the project exists in a way a repository does not. Free tools do this: OBS Studio on any platform, the built-in recorder on macOS and Windows, Peek on Linux. Loom is the paid product people reach for; nothing about a forty-second clip needs it.

Keep it short and unnarrated. Nobody watches minute two.

The mistake to avoid

Writing the page as a tutorial. “First, we import pandas. Then we load the data.” The reviewer is not learning your project; they are making a decision about you, and every sentence that teaches them Python is a sentence not spent on evidence.

Write for a peer who could have built it themselves, and tell them the parts they would not have predicted.

The limitation

This only works if the project is real. Inventing a user count is checkable (a reviewer may ask which cooperative, or when the last commit was, or what the dispatchers complained about) and the conversation ends there. One small real project beats an impressive imaginary one, and it is much less exhausting to talk about.