13.5 Portfolio and writing

What this is and why it exists

Your portfolio is the interface to your work, and it gets about ninety seconds. Most portfolios fail at the reading stage rather than the quality stage — the work is fine and nobody could tell in the time available. This topic is how to make it legible: repositories that explain themselves, one written piece per project, a CV that fits on a page, and the habit that signals more seniority than any result — saying plainly what your work does not do.

The vocabulary

• Pinned repository — one you have chosen to display at the top of your profile.
• README — the file a repository opens with, and the only part most people read.
• Technical post — a written account of the decisions in a project.
• Signal — something in the material that tells a reader you have done this before.
• Limitations — what the work cannot do, stated by you rather than found by them.

The mental model

Assume ninety seconds and design for it. A reviewer opens your profile, reads a line of description, glances at four pinned repositories, opens one README, scrolls it, and decides whether to spend more time. Everything below is about making that path lead somewhere.

Your profile is a shop window and most people leave it empty. A single sentence saying what you do and what you are looking for. Four pinned repositories — the capstones — ordered with the strongest first. A short profile page listing them with one line each and, where they exist, a live link. A link to something running is worth more than any description, and the second capstone's demonstration is exactly that.

READMEs are where portfolios are actually won and lost, and there is a structure that works.

What it does, in one sentence, before anything else, in plain language a person outside the field understands.

A picture or a sample. A screenshot of the demonstration, or a request and its response. This is the highest-value item in the file — a reader who sees output in five seconds has understood more than three paragraphs would convey.

A link to it running, where it runs.

The result, honestly: your number, the baseline beside it, and what was measured on.

How to run it, tested from nothing on a clean machine. Instructions that assume something already installed are the commonest defect, and the compose file from the container topic is the honest test of them.

How it works, briefly — the architecture in a short paragraph and, if it helps, a diagram.

Limitations, which get their own section below.

Three things to avoid: a wall of text before anything concrete, a badge collection, and a README explaining the technique rather than your project. The reader knows what a gradient booster is; they want to know what you built and whether it works.

One technical post per capstone, and the subject is the decisions rather than the tools.

Nobody needs another article explaining what a transformer is. What is worth reading — and what demonstrates capability — is the reasoning: why that dataset, why that split, what you tried that failed, what surprised you, what the measurements said, what you would do differently. A post about a decision you got wrong and corrected is more convincing than one about a result, because it shows the process rather than the outcome.

And writing is also how you find out whether you understood what you built. The point in a draft where you cannot explain why you did something is the point where you did not know, and that discovery is worth the afternoon on its own. Publish somewhere stable, keep it short, and link it from the repository — a thousand words that say something beats three thousand that summarise a tutorial.

A one-page CV, and the constraint is the exercise. One page for roles in this field means cutting most of what you could include, and cutting is what makes it work.

What earns space: the projects, with a line each saying what and the measured result. Skills that are actually yours, grouped and not rated out of five. Experience, described by what you did and what changed rather than by what you were responsible for. Education, briefly. And links — the profile, the demonstration, the writing — because the links are how a reader gets to the evidence.

What does not: a list of every library you have opened, an objective statement, a photograph, a rating chart, and anything you would not want to be questioned on. Everything on the page is an invitation to a question, so put a technique there only if you can discuss it.

Then the habit this topic exists to teach, which is the strongest signal of experience an interviewer can hear: state your limitations credibly, and without apology.

"This works on the classes I collected, in the lighting I collected them in, and I do not know how it behaves outdoors." "The retrieval number is measured on fifty questions I wrote, so it is indicative rather than precise." "It has not been tested above ten requests a second and I have not measured what breaks first."

That reads as seniority, and claiming everything works reads as inexperience — because reviewers are calibrated on this. Everyone who has shipped something knows every system has edges, and somebody who cannot name theirs has either not looked or is hiding them. Both are worse than the limitation itself.

The delivery matters. Without apology means stating it as a fact, not as a confession: not "unfortunately I did not have time to", but "this is scoped to the classes I collected; extending it would need data from other conditions". The first sounds like a failure; the second sounds like a decision, which it was.

And it makes the conversation better. A stated limitation invites the question you have thought about — "how would you extend it?" — instead of the one you have not. The best portfolio conversations are about what somebody would do next, and you get there by having been honest about where you stopped.

Two closing habits. Ask somebody outside the field to look at your profile for ninety seconds and tell you what you do — the gap between their answer and the truth is your actual portfolio problem, and it is almost never the quality of the work. And keep it current: a profile whose newest item is a year old says something you did not intend, and a small honest update is better than a large abandoned plan.

What you should now be able to explain or do

Design for a ninety-second read and say where most portfolios actually fail. Set up a profile with a sentence, four pinned projects and links to running things. Write a README with the seven parts, leading with a sentence and a picture, and test the instructions from nothing. Write one post per project about decisions rather than tools. Cut a CV to one page and say what earns space. State limitations credibly and without apology, and explain why that reads as seniority. Get an outside ninety-second read and keep the profile current.

Check yourself