Writing for Developers
Most of a developer advocate's work ends up as text: docs, posts, release notes, forum answers, emails to the product team. Developers read all of it the same way, in a hurry and with a task in mind. They scan the first line, the headings and the code, and leave the moment they find what they came for, or decide it isn't there.
The rule
Put the reader's task first, and cut every word they'd skip.
Writing for developers comes down to a handful of habits:
- Front-load. The first sentence says what this is and what the reader gets. Background can come later, if at all.
- Short sentences, active voice, "you". "Call
forecast()with a latitude and longitude" beats "The forecast method may be invoked with location parameters." - Concrete over abstract. One example teaches more than three adjectives.
- One name per thing. If it is an "API key" in one paragraph, don't call it a "token" in the next and a "secret" in the one after. Readers will assume those are three different things.
- Code that runs. Every snippet has been copied, pasted and run exactly as printed.
Here is the difference in practice.
Before:
It should be noted that, in order to enable the utilisation of the forecasting capabilities provided by the Rainkit platform, it is necessary for an API key to be obtained by the user.
After:
To call Rainkit, you need an API key. Get one free from your dashboard.
The second version is a quarter of the length, and it tells the reader what to do.
The shortcut
Edit every draft in two passes:
- The first-line test. Read only the first sentence. Does it tell the reader what they will be able to do? If not, rewrite it until it does.
- The delete pass. For each sentence, ask: "Would the reader miss this if it were gone?" If not, delete it.
The draft
"We are thrilled to announce that, after months of hard work, our amazing team has shipped a new version of the Python SDK which, among many other improvements, now supports async."
The trap is writing excitement instead of information. Enthusiasm is fine in a talk, but on the page it takes up the exact spot where the reader was looking for the point.
Drills
Answer fast — trust the rule.
Which sentence is the clearest instruction?
A doc calls the same thing "API key", "token" and "secret" in different paragraphs. What is the problem?
What should the first sentence of a release note say?
During the delete pass on a release note, which phrase should go first?
Remember
- Put the reader's task first, and cut every word they'd skip.
- Shortcut: the first-line test, then the delete pass: "Would they miss it?"
- Trap: excitement instead of information, and several names for one thing.