The person who runs the engineering blog sends you a friendly message. They heard about the migration you led last quarter and would love a post about it. Around a thousand words, no rush, maybe by the end of next month. You say yes, and then spend an evening convinced you have nothing worth saying in public.
That feeling is very common, and it is usually wrong in a specific way. You are comparing your first draft to the polished posts you have read from well known engineers. But readers of a company blog are not looking for brilliance. They want to know what really happened when someone like them faced a problem like theirs.
Start with the story, not the lesson. What were you trying to do, what went wrong, and what did you change? A migration that went perfectly makes a dull post. One where the second weekend went badly and you found out why is the post people forward to their team.
Write down the details only you know. The number of tables, the query that took nine hours, the moment someone noticed the dates were off by a day. Specifics are what make a post believable, and they are where your authority comes from. Nobody else has your notes.
Do not try to sound like an expert. Write the way you would explain it to a new colleague over lunch. Plain sentences, honest about what you are still not sure of. Readers trust a writer who says we think this was the cause more than one who claims to have everything figured out.
Ask for help early. Send a rough outline to the blog editor before you write the whole thing. Ask a teammate who was there to check you have remembered it right. Neither of them will think less of you for it.
Expect a comment or two you disagree with when it goes live. That is the price of writing anything useful, and it does not mean you were wrong to publish.
And when it is out, add it to your list of things you have done. You explained real work to strangers, and that is a skill worth having.
– Asael Shinder
Top comments (0)