Blog Posts Developers Finish
Meera's first blog post for Rainkit was called "Thoughts on Weather Data". It had 2,000 words, no code until paragraph nine, and most readers left within a minute. Her second post, "Flag rain-hit deliveries in 30 lines of Python", was shared in three developer newsletters. The difference was not the writing talent. It was the shape.
The rule
One problem, one working solution, and proof that it works.
Developer blogs carry several kinds of post: step-by-step tutorials, stories about solving a hard problem, explainers, and announcements. The ones developers actually finish tend to share one shape:
- A title that makes a promise. It names the problem or the result: "Flag rain-hit deliveries in 30 lines of Python", not "Some thoughts on forecasts".
- An opening that says who it's for and what they'll have at the end, in the first paragraph.
- Prerequisites: language version, SDK version, accounts, anything the reader needs before starting.
- Steps with code that runs, each one small enough to check before moving on.
- Proof: the output, a screenshot, a number. Show that it works.
- Next steps: the full code in a public repo, related docs, a harder variation to try.
Two habits protect the reader's trust. Test the code in a clean environment, following the post exactly as written, because your own laptop has things installed that the reader's does not. And note the versions and the date, so a reader two years from now knows what they are looking at.
The shortcut
Write the title and the last paragraph first. The title is the promise; the last paragraph is the proof. Everything in between has one job, which is to get the reader from the first to the second. Anything that doesn't help with that gets cut, however interesting it is.
The promise
Title: "Flag rain-hit deliveries in 30 lines of Python".
Drills
Answer fast — trust the rule.
Which blog title makes the clearest promise?
Where should a tutorial post say who it is for and what the reader will build?
What is the best way to make sure a post's code works for readers?
Meera's draft has a long section on the history of monsoon forecasting, but the post promises a delivery-alert script. What does the shortcut suggest?
Remember
- One problem, one working solution, and proof that it works.
- Shortcut: write the title (the promise) and the last paragraph (the proof) first. The middle connects them.
- Trap: untested code, and interesting detours that don't serve the promise.