A Software Developer’s Guide to Technical Writing
The Economist once ran an advert asking for an article of scientific journalism to compete for an internship spot on its team. The company specifically said that it would rather have a scientist who could write than a journalist who knew some science.
With that in mind, as an experienced software developer and technical writer, here are my tips for writing technical articles. I’m referring to articles where the audience is tech folk looking for a heads-up on a technology product, platform or tool.
Habits and Tools
If you have ever considered writing and you work with technology, you should definitely put yourself in the frame for creating technical articles. Yes, writing only improves with practice, but you don’t need to possess any mystical writing talent. In the days of social media, almost everybody writes. And as any editor knows, engagement is not quite the same thing as literature. You might want to write about a new technology you have just used or are interested in using, or maybe you feel duty bound to promote one of your existing go-to technologies.
If you’ve ever spoken at a conference, you understand that this is a form of barrier challenge. You chose to accept it, and after you do it once it is a matter of repeating the pattern. Writing is similar; find the right tools and the right sources, and then find your best times to get words on the page.
Maintaining the habit is harder. I’m sure you know someone who has started a novel — but you probably know fewer people who have finished one. Fortunately, writing about 1000 words is nowhere near as taxing. You may start off with not enough words, then later have far too many. Rereading drafts and editing is the bread and butter of scribbling. You only have that blank page once.
It turns out that writing tools do matter. Technical articles mix things like text with diagrams, images and code. Formatting these correctly — and then exporting them into the final publication platform and checking the format is still ok — is not always trivial. I might write in Notion, export in Markdown, then push into WordPress. If you are planning to write more than one article, then getting this process smooth is an early necessity.
Be a Car Horn
The other Shibboleth to get around is that if you don’t fully understand a technology, you can’t possibly write about it. The purpose of most technical posts is to be a car horn — to announce that what you are writing about is here, relevant, and should be noticed. You can also elucidate what is behind the technology, what the thinking was that brought it into being, and how it helps people today.
Of course, you want to avoid mistakes but remember: you are a car horn, not a white paper. Re-explaining things in your own voice is also fine. In general, you only really learn things you almost already knew, so reading a different explanation of the same thing is often quite illuminating.
Try to introduce concepts based on how you first came across them, not just how Google sees them. Putting yourself in a story is more than acceptable — indeed, it can be the unique angle needed.
Introducing internal terms or idioms, unless they actually express something without further context, can make things harder to comprehend. For example, Rails is described as “opinionated” — which is both truthful and describes well what to expect later. Whereas saying that Java has “garbage collection” doesn’t really help with understanding the language itself. Show people the steps down to the cellar by all means, but don’t disappear down them yourself.
An Example
Here is an example approach. As part of an article, how would you explain the basics of SQL in a paragraph?
Should you start by explaining that SQL is a DSL (Domain Specific Language — and yes, unless they are obvious, you should also spell out acronyms)? Yes, because there are firm consequences for knowing that you can do everything with a limited set of commands. Should you explain Oracle’s history? No, but maybe you can mention when you first worked with table data, to help set context. Should you explore relational databases? You would have to explain a bit about tables and schemas, of course. What about “primary and foreign keys”? Try to avoid using the internal term itself initially; start with terms like “refers to” or an “index of.”
Onto diagrams and code listings. Clearly, a table is very easy to visualize and draw (which is why it is such a pervasive idiom) and you can trivially show both a query and the tables it works with:
TABLE fruit
| Name | Origin |
|---|---|
| Apple | Kazakhstan |
| Banana | Philippines |
| Cherry | Romania |
TABLE nation
| Name | Continent |
|---|---|
| Kazakhstan | Europe / Central Asia |
| Philippines | Asia |
| Romania | Europe |
How do we ask SQL from which continent apples originate?
|
1 2 3 4 5 6 7 8 9 10 11 |
>select fruit.name, nation.continent from fruit, nation where fruit.origin = nation.name and fruit.name = 'apple'; +-------+-----------------------+ | name | continent | +-------+-----------------------+ | apple | Europe / Central Asia | +-------+-----------------------+ |
This is a weak schema and a trivial query, but it points out the purpose and use of SQL, as well as hints at the possible issues that you can then talk about if relevant. Note that a better-formed pair of tables may not act as such a simple example. It’s worth repeating that point — very efficient code may well be harder to fathom than simpler code using familiar structures.
Also, instead of talking about primary and foreign keys, a diagram is more effective:
Note, however, that there is no reason to limit your example to employees, departments and office locations! It’s better, of course, to use examples that you care about.
Focus on the Journey (and Other Final Tips)
You will naturally use rhetorical devices to persuade your audience of your points.
Comparing products in a head-to-head fashion is ok when comparing matching goods, but much less useful for merely similar technologies. Once chosen, you generally have to use a technology from beginning to end — so it is more useful to show a full user journey. Comparisons are useful for making elevator pitches (“Sharknado is like Jaws meets Twister”) but from then on, focus on the journey. Install it, follow the documentation, try examples. Where did you trip up?
I love using websites that work as a sandbox for a technology. For example, when looking at regex, it was useful to show immediate examples with regexr. Not only does it make it easier to explain — look at my sandcastle! — it also proves that the technology is flexible enough to be expressed in several ways.
Putting technologies in a timeline (birth, growth, possible death) is a natural device to give context, but it’s even more useful for spotting shifting needs and possible built-in issues. “It was started before cloud computing” tells your audience implicitly where a new direction might lie.
The last thing I would add reads like long-standing life advice: don’t be afraid of initial mediocrity. It might be fatal for a pilot, but you probably won’t cause much consternation if your first technical article doesn’t land properly. Try a few times, at least, before coming to any conclusions.
