Write a Portfolio Project Writeup People Finish. A Build Next Stack field guide for learners shipping small projects.
Lead with the problem not the stack list
Readers bounce when the first screen is logos—React, Tailwind, Supabase—in hero font. Open with two paragraphs: who had the problem, what they tried, what still failed. Stack logos belong after motivation, smaller, linked to docs if needed.
Problem-led leads respect reader time. They also force you to know why the repo exists before you decorate it. If you cannot write the problem without stack words, the project may be practice—which is fine, but say practice port of X pattern honestly.
Readers on mobile see two paragraphs before scrolling. Make paragraph two describe the cost of the problem—late fees, double data entry, missed reminders—not your motivation story unless motivation clarifies the user.
Cost language keeps skimmers: three apps, twenty minutes every Monday beats I wanted to learn React in paragraph two.
One screenshot with a caption that teaches
One strong screenshot beats twelve thumbnails. Choose the screen that shows the core outcome—dashboard with overdue totals, not login page. Caption format:
Overdue totals update after CSV import; yellow rows are 30+ days.
Captions teach non-readers and skimmers. Avoid homepage screenshot—say what the viewer should notice. Alt text matches caption; accessibility and SEO both win.
Annotate sparingly—one arrow to the feature you discuss in the next section. Decoration arrows everywhere look like marketing, not builder documentation.
If the UI is not visual yet, screenshot the CLI output or test runner green bar with caption explaining what passed—finishers need evidence, not polish.
Architecture in three bullets max
After motivation, three bullets describe data flow:
- Ingest: nightly CSV upload to storage bucket
- Process: serverless function parses rows, writes to Postgres
- Surface: static dashboard reads API, highlights overdue rows
Diagrams optional; bullets mandatory. Readers finishing your writeup want mental model fast, not a UML certification exam.
If architecture needs more than three bullets, scope may be too large for one writeup—or you are documenting implementation details before the reader cares.
A decisions section beats a features list
Replace bullet features with three decisions and why:
- CSV over live bank API — faster MVP; users already export from banks
- Email reminders manual trigger first — validate copy before automating schedule
- No auth v1 — single-user dogfood; auth planned after import stable
Decisions show how you think. Features show what exists—readers can see features in the screenshot. Decision sections age better when stack changes; feature lists go stale when you rename buttons.
Include one decision you reversed later—manual email first, automate after copy validated—to show iteration without hiding false starts.
Short code snippet with context
One snippet, ten to twenty lines, with a sentence before and after:
Import maps messy bank headers to a canonical schema before insert.
Then the snippet. Then: Without mapping, duplicates appeared when banks changed column order between exports.
Snippets without story feel like padding. Story without snippet feels hand-wavy. Together they reward readers who finish.
Link full repo for depth; writeup stays readable on mobile without horizontal scroll hell.
Choose snippet lines that changed behavior—not config boilerplate. Readers finish when snippet teaches a decision they can argue with, not when it shows you ran a formatter.
End with what you would redo
Close with a short Next time list—two items max:
- Start with mapping UI before backend insert—users could validate headers earlier
- Add observability on import failures—debugged blind via local logs only
Redo sections signal growth without fake humility essays. They also give readers a reason to check commit history later.
Do not end with thanks for reading or author biography—link repo and demo instead. Finish lines should move hands toward code or live demo.
Keep total writeup under eight minutes read time on mobile—roughly 900 to 1,100 words in the body you control, excluding auto-generated theme chrome.
Swap hero screenshot seasonally when UI changes—stale screenshots signal abandoned projects faster than missing sections.
Length targets that respect mobile readers
Structure length by section budget:
- Problem: 120–180 words — two short paragraphs
- Screenshot + caption: one image, 40–60 words
- Architecture: three bullets, no paragraph longer than two lines
- Decisions: three numbered items with because clause each
- Snippet: 10–20 lines max with wrap enabled
- Next time: two bullets
Read aloud once; cut any sentence you stumble on. Stumble usually means jargon or two ideas crammed together.
Link out to deep docs for setup steps—writeup is tour, not manual. Readers who finish should know whether to clone; setup belongs in README.
Test on phone preview before publishing. Horizontal scroll on code blocks kills finish rate—shorten variable names in snippet if needed for display.
Add a single demo link above the fold—Try import with sample CSV—so finishers can act immediately. Dead-end writeups feel like résumé padding; live demos feel like builder logs.
Ask one reader where they stopped scrolling. If answer is architecture paragraph, cut prose and trust the three bullets. Finish rate beats elegance.
Draft the problem paragraph first
Before screenshots or snippets, write two problem paragraphs in plain text. Read aloud. If you finish without mentioning a framework name, continue the writeup. If not, narrow the problem until you can.
Portfolio writeups people finish are short, decision-heavy, and honest about tradeoffs—not résumé keyword soup. Write for the reader who has ninety seconds and might still click your demo.
Publish problem plus screenshot first; add architecture and snippet after a friend confirms they scrolled past the fold without getting lost.
Time yourself reading aloud once. Over six minutes means cut a section, usually redundant architecture prose duplicate of the three bullets.
Update writeup when decisions change—stale decision sections erode trust faster than missing features list. One paragraph patch beats silent drift.
Finished writeups include one link that works on mobile—broken demo links waste every careful paragraph you wrote above them.
When in doubt, cut a features bullet and strengthen one decision paragraph—readers remember tradeoffs longer than checkbox lists.