The reflex
People start asking for your opinion. A thread about your practice got passed around, you get invited to talk about it. So you write more often, about what you would do more than what you did. The result gets rounded up with every version. “I don’t know” disappears, because a reference is supposed to know.
The builder’s reflex
Only write about what you built or tried. Say what failed, what you didn’t measure, and what you are still looking for.
Why
A reference is worth what someone can rebuild from it. A piece that rounds up the result wastes the time of whoever tries to reproduce it. They won’t tell you. They will stop reading you.
Two posts describe the same migration. The first announces response times cut by three. The second says “cut by three on the catalogue pages, no effect on checkout, and we don’t know why yet”. The team about to migrate passes the second one around.
Writing to stay visible has a quiet cost. The time spent keeping an audience fed comes out of the work that gives you something to say. A year later, you are commenting on a craft you practise less and less.
This is not an invitation to go quiet. Shrinking a real result misleads as much as inflating it. Say what you did, at its actual size.
Try this
Take your last post or talk about your work. For each claim, note whether you measured it, saw it once, or assumed it. Fix the ones that look sturdier than they are.
In the next one, add a line on what you don’t know yet. If you haven’t built anything since the last one, don’t write the next.
From where you sit
- Engineering: separate what was measured in production from what was tried locally.
- Management: when you present the team’s work outside, don’t make it cleaner than it was.
- Recruiting: a “what didn’t work” line in a portfolio is a signal, not a flaw.
To discuss
Which piece of writing helped us most, and what did it admit?