Most engineering portfolios are highlight reels: a screenshot, a stack list, a sentence of praise. They're pleasant and they're unfalsifiable. Documentation is a better format, because documentation has to be specific or it's useless.
The problem with the highlight reel
"Built a scalable checkout with Next.js and Stripe" tells a reader nothing they can evaluate. Scalable to what? Which part was hard? What broke first?
The reader you care about — an engineer deciding whether to interview you — is trying to answer one question: does this person reason well about systems? A screenshot can't answer it. A trade-off can.
The template
Five sections, always in this order:
Problem
What was broken and what "fixed" was defined as, before any solution language. If you can't state the definition of done, you didn't have one.
Architecture
The shape of the system and, more importantly, why it has that shape. One diagram, then the two or three decisions that determined it.
Stack
Concrete choices, briefly. This is the least interesting section and it should be the shortest.
Results
Numbers with a before and an after. If you have no numbers, say so — a stated absence reads as honesty, an implied one reads as spin.
What I'd do differently
The section that does the work. This is where a reader decides whether you learn.
Why the last section matters most
Everything above it describes a system. That section describes you — how you evaluate your own decisions once the pressure that produced them is gone.
It also has a useful side effect: it's very hard to write a convincing "what I'd do differently" about a project you didn't actually build. The section self-verifies.
Tip
Write it as a decision you'd revisit, not as an apology. "I'd persist shipping quotes with an expiry from day one" is engineering. "I should have been more careful" is nothing.
Structure is the whole trick
A docs-shaped portfolio also solves a practical problem: consistency. When every project has the same five headings, a reader can compare them, skip to the part they care about, and trust that nothing was quietly omitted from one page that appears on another.
That's the same reason product documentation is structured. The format is doing some of the work that your prose would otherwise have to do alone.
Cost
An hour per project, most of it spent on the architecture diagram, and a habit of writing the page while the reasoning is still fresh rather than six months later. Cheaper than the alternative, which is re-deriving why you made a decision in the middle of an interview.