"Fixed a bug today" is not a post. Neither is a description of the bug, however gnarly.
But some bug fixes make excellent content, and it is worth being precise about which, because the instinct is wrong. It is not the hardest bugs. It is the ones with a surprising cause.
The shape that works
A good bug post has four parts:
- What you expected
- What actually happened
- Why, and this is the part that matters
- What it means beyond this bug
The third part is where the value is. A bug caused by a typo has no third part. A bug caused by an assumption you did not know you were making has a good one.
An example
Here is a real one from building Noomachy DevTracker.
We had a validator that catches em dashes in generated posts, since they are one of the strongest tells of machine written prose. Then we did a repo wide sweep to remove em dashes from our own source.
The sweep rewrote the detector's own regular expression. /[—–]/ became /[--]/, which is a character class containing only a hyphen. The check silently became a hyphen detector.
Every test still passed, because the sweep had also stripped the em dash out of the test fixture whose entire job was to prove em dashes get caught. The fixture now contained a hyphen, the detector now matched hyphens, and the test agreed with itself.
The fix was two lines: write the regex with unicode escapes, and write the test fixture with an escape too.
Why that one is a post and "fixed a typo" is not
It contains a transferable idea: a text transformation applied to a whole repository can rewrite the code that detects the thing being transformed, and the tests can move with it so that nothing fails.
Someone who will never use our product can take that away. That is the bar.
The parts people get wrong
Too much setup. Three paragraphs establishing the system before the bug appears. Start closer to the problem. The reader can pick up context on the way.
Explaining the fix and not the cause. The fix is usually boring. The cause is the content. If your post is mostly the diff, it is a changelog.
No generalisation. If the post ends at "and then I fixed it", the reader gets nothing portable. One sentence of "the general version of this is" changes that.
Performing the difficulty. "Spent 6 hours on the gnarliest bug of my career" and then it is an off by one. The difficulty should be evident from the content rather than asserted in the opening line.
The honest version of hard
If a bug did take four hours, say so plainly and let the reason carry the weight:
The fix was one line. Finding it took four hours, because the failure looked like a network problem and was actually a timezone problem.
That is better than dramatising it, and it sets up the third part properly.
The ones to skip
Not every bug is a post. Skip it when:
- The cause was a typo
- The cause was you not reading the documentation
- Explaining it requires more context than the insight is worth
- The generalisable lesson is something everyone already knows
The last one catches most of them. "Always check for null" is not a finding.