How to Document Work So Someone Can Verify It

The write up is the part they read

Here is something that surprises people: most of the readers who matter will never run your project. They will read what you wrote about it, look at a screenshot or two, and form a judgement in a couple of minutes.

That is not laziness on their part. It is the only practical option when you are one of many applicants. Which means the write up is not a wrapper around the work. For most readers, it is the work.

It is also the only part a stranger can verify. They cannot see the four evenings you spent. They can see whether your account of what happened is specific, coherent and honest, and those three qualities are surprisingly hard to fake.

The five sections

Keep it to one page. Longer is not better and almost nobody reads to the bottom.

The problem. Who was losing time or making mistakes, and what it cost them. Two or three sentences. Concrete beats general every time.

What you built. What it takes in, what it produces, and how someone would use it. Plain language, no tool names in the first sentence.

What you tried that did not work. This is the section people delete and it is the most valuable one. Two things you attempted, why each failed, and what you did instead.

What you would do differently. Shows you can look at your own work critically. One or two things, specific.

Where AI helped and where you decided. Covered properly below, because getting this wrong causes real damage.

Be exact about what you did and what the tool did

Never present AI-generated work as entirely your own. Not because someone will catch you, though they well might, but because the interview will go somewhere you cannot follow.

Being precise about this is not a confession. It is a demonstration of judgement, which is exactly what an employer is trying to assess. The interesting question is never whether you used AI. Everyone does. The interesting question is what you decided.

Look at what the good version does. It names a rule you wrote, a specific failure, and a decision you made because of that failure. That chain is what capability looks like on paper.

Getting the first draft out

Writing about your own work is harder than doing it. Use your notes and let a tool interview you rather than write for you.

I need to write up a project for a portfolio. Do not write anything yet.
Interview me first. Ask one question at a time, about ten in total, covering:

who had the problem and what it cost them
what I actually built and what it takes in and produces
what I tried that failed, and what I did instead
which specific decisions I made, and what the AI tool generated
what is still manual or still broken
After the last answer, give me a one page write up in plain language using only what I told you. Do not add anything I did not say, and do not use flattering adjectives about me.
Start with question one.

Then check the draft for the thing you cannot see in your own writing.

Here is a draft write up of my project. Go through it sentence by sentence and mark each one as:
CHECKABLE: a reader could verify this by looking at the work
VAGUE: sounds good but cannot be checked
OVERCLAIM: implies I did more than the text actually supports
For every VAGUE or OVERCLAIM, suggest a plainer replacement or tell me to delete it.
[paste your draft]

Screenshots, before, and after

Include two or three images: the input, the output, and one thing going wrong. That third one is unusual and it is memorable. It also proves you tested, which most portfolio pieces quietly fail to demonstrate.

Give a before and after in whatever units are honest. Two hours to twenty minutes. Forty errors a month to a handful. If you never measured, say you never measured, and describe the change qualitatively instead. An unmeasured claim dressed up in numbers is the fastest way to lose a reader who knows the domain.

One last pass

Read it as a stranger. Better, ask a tool to read it as one.

You are a hiring manager who has never met me and has two minutes. Read this project write up and answer:

What can this person actually do, based only on what is written here?
What is still unclear?
Which single sentence would you challenge first in an interview, and what would you ask?
Is there anything here that reads as inflated?
Be blunt.
[paste your write up]

Whatever they say they would challenge first, make sure you can answer it. That is the next lesson.