Writing about your work in public
By the end: You can turn a project into a short public write-up that people read, and that works as evidence in a job search.
- One idea per post
- Lead with the result and a figure
- Show the code
- Honest limits build trust
New to writing & communication? Turning a result into something someone else can use — a paper, an internal report, a design document. Concretely it is four decisions: what the single claim is, in what order the evidence has to arrive for a reader to accept it, which figures carry the argument without their caption, and what you did not show, said plainly rather than left for the reader to notice. Why it matters
A project that exists only on your own machine is invisible. This section is about turning one into a short public write-up people finish reading: one idea per post, the result and the figure at the top instead of saved for the end, the code shown rather than described, and the limits stated plainly. Being straight about what your result does not show is what makes a reader trust the part that it does.
Why it matters for you#
A clear write-up of a small project, with code and numbers, shows what you can do and how you think in a way a CV cannot. It gives an interviewer something concrete to ask about, and it keeps working for you after you publish it.
The mechanism is worth understanding, because it changes what you write. An interviewer reading a CV has to take every line on trust and has no way to ask a better question than the one on their sheet. An interviewer who has read four hundred words in which you measured something, found it smaller than you expected and said so, has already seen you reason, and the conversation starts several steps further in. That is bought by the honesty rather than by the size of the result, which is why a careful small post outperforms an impressive vague one.
One idea per post#
The commonest way a good write-up fails is that it contains three findings. Each one dilutes the others, the title can only name one of them, and a reader who would have shared the post cannot say what it was about in the message they would have sent with it. If you have three things, you have three posts, and the second and third are nearly free because the setup is already written.
The test is the same as for a paper: write the title as the finding, and if the title needs an and in it, you have two posts. A post about chunking strategies and embedding models and a cost analysis is a post nobody finishes. A post called Chunk boundaries mattered more than chunk size is one somebody forwards.
The shape of a good post#
- 1.The finding in the title or first sentence.
- 2.One figure that shows it.
- 3.What you did, briefly, with a link to code.
- 4.What surprised you, and what did not work.
- 5.What you would try next.
The first item is the one that gets argued about, because the instinct is to build up to the result the way you arrived at it. Resist it. A reader has given you fifteen seconds to justify the next five minutes, and a paragraph of context spends that budget on something they already know. Put the number in the first sentence. Everything after it is now being read by someone who has decided the post is worth reading, which is a different and much more forgiving reader.
The fourth item is the one that separates a post people trust from a post people skim. What did not work is the part nobody else publishes, and it is the part that is most useful to a reader who is about to try the same thing. It is also the cheapest possible signal that you are reporting rather than selling.
One written out#
Here is the whole thing at the length it should be. The study is invented, and deliberately small; the shape is what to copy.
My LLM judge agreed with itself 91% of the time and with me 74%
---------------------------------------------------------------
I graded 200 support-bot answers three times: twice with the same judge
prompt at temperature 0, and once by hand. The judge agreed with its own
earlier verdict on 182 of 200 (91%). It agreed with me on 148 (74%),
which is Cohen's kappa of 0.42 -- moderate, and lower than I would have
guessed from watching it work.
[Figure: a 2x2 confusion matrix, my label against the judge's. The
off-diagonal is lopsided: the judge passes 41 answers I failed, and
fails 11 I passed.]
WHAT I DID. 200 answers sampled from a week of traffic, stratified so a
quarter were ones the bot had flagged as low confidence. One judge
prompt, asking for pass or fail and a reason, run twice with the same
seed and temperature 0. I graded all 200 myself first, without seeing the
judge's output, and I did not revise my labels afterwards. Code and the
anonymised answers: github.com/<me>/judge-agreement.
WHAT SURPRISED ME. Self-consistency at 91% looked like a good sign and
was not informative. A judge that always says pass would be 100%
self-consistent. The number that mattered was the agreement with me, and
almost all the disagreement was in one direction: the judge is lenient
about answers that are fluent and wrong.
WHAT DID NOT WORK. Asking the judge to be strict moved raw agreement
from 74% to 76% and kappa not at all -- it started failing answers I had
passed, at about the rate it stopped passing ones I had failed.
LIMITS. One judge prompt, one model, one product, and one grader, who
is me, and I knew which system produced the answers. Kappa against a
single unblinded human is an upper bound on how good this judge is, not
a measurement of how good it is.
NEXT. Two graders, blinded, on the same 200, so I can see whether 74%
is the judge's ceiling or mine.Read the limits paragraph again, because it is doing more work than it looks. It does not say results may not generalise. It names four specific conditions, admits the grader was unblinded, and then draws the consequence out loud: this is an upper bound, not a measurement. A reader who knows the area now trusts the rest, and a reader who does not has been told exactly how much to conclude. That paragraph costs four sentences and buys everything else in the post.
Showing the code#
A link to a repository is not showing the code. The reader who would have been convinced by your code will not clone anything, so put the ten lines that contain the idea directly in the post — the metric, the loop that produced the number, the prompt — and link the repository for the person who wants the rest. Ten lines in the page get read; a repository gets a click from one reader in fifty.
What the repository has to earn is the second click. One command in the README that reproduces the headline number, the data or a generator for it, and the versions you used. A repository where the reader has to work out which of eleven scripts made the figure converts an interested person into someone who assumes the result would not reproduce.
Keep it honest#
Say what the result does not show: the small scale, the single dataset, the seeds you had. Readers trust writers who mark their own limits, and experts will notice if you do not.
Two habits carry most of this. Give every number the thing it was measured on and the variation you saw, because a number without either is a claim rather than an observation. And when you do not know why something happened, write that you do not know, rather than the plausible mechanism you thought of afterwards. The invented explanation is the single thing most likely to be the one an expert reader can tell is wrong, and it costs you the parts of the post that were right.
Publish before it is impressive
The post that never gets written is almost always the one waiting for a better result. A small measured finding, honestly bounded, is publishable the week you have it, and it is more useful to a reader than a large project described in general terms. Nobody has ever been marked down in an interview for a careful write-up of something modest.
Where people go wrong
Waiting until the work is impressive enough. A careful write-up of a small result is more valuable than a large project nobody can see.
If this comes up in an interview
Tell me about something you have written or shared publicly about your work.
Describe the post, the one idea it made, the evidence behind it, what readers asked or pushed back on, and what you changed as a result. Having a link ready is better than any description.
Then they push further
What did the post say it could not establish?
Answer this specifically, because it is the real question. Name the conditions — one dataset, one model, one grader, unblinded — and the consequence you drew from them, such as that the number is an upper bound rather than a measurement. An interviewer is checking whether you know the difference between what you observed and what it supports, and that is the same judgement they need on the job.
What gets marked up. Marked up for a link, a number, and a limitation the candidate volunteers rather than concedes. A polished description of a project with no result in it scores below a small measured finding honestly bounded.
Build this: Write a 600-word post about one result from this atlas's practice items, with one figure and a code link, and publish it wherever people in your field read.
This is one section of Writing & communication, 16 hours across 4 sections. Read it in full to get the whole topic in order.