The Economist once ran an ad asking for a science journalism article to compete for an internship spot on its team. The company specifically said it would rather have a scientist who could write than a journalist who knew a little about 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 people looking for information about a product, platform, or tech tool.
Habits and tools
If you’ve ever considered writing and work with technology, you definitely need to put yourself in the frame of creating technical articles. Yes, writing only gets better with practice, but you don’t need to possess some mystical writing talent. In the age of social media, almost everyone writes. And as any publisher knows, engagement isn’t quite the same as literature. You might want to write about a new technology you’ve just used or want to use, or maybe you feel compelled to promote one of your existing favorite technologies.
If you’ve ever spoken at a conference, you understand that this is a form of barrier challenge. You have chosen to accept it, and after doing it once, it is a matter of repeating the pattern. The writing is similar; find the right tools and sources, then find your best times to get words on the page.
Maintaining the habit is more difficult. I’m sure you know someone who has started a novel, but you probably know fewer people who have finished one. Fortunately, writing around 1000 words isn’t nearly as taxing. You can start with not enough words, then later have way too many. Proofreading drafts and editing are the bread and butter of doodling. You only have this blank page once.
It turns out that writing tools matter. Technical articles mix things like text with diagrams, images, and code. Formatting them correctly – then exporting them to the final publishing platform and checking that the format is still correct – is not always trivial. I could write in Notion, export in Markdown, then push into WordPress. If you intend to write more than one article, then streamlining this process is a must.
Be a car horn
The other Shibboleth to get around is that if you don’t fully understand a technology, you can’t write about it. The purpose of most tech posts is to be a car horn – to announce that what you’re writing is here, relevant and needs to be noticed. You can also elucidate what is behind the technology, what was the thought that brought it into existence, and how it helps people today.
Of course, you want to avoid mistakes, but remember: you’re a car horn, not a white paper. Re-explaining things in your own voice is also acceptable. You usually only really learn things you almost already knew, so reading a different explanation of the same thing is often very enlightening.
Try to introduce concepts based on how you first encountered them, not just how Google sees them. Getting into a story is more than acceptable – indeed, it may be the unique angle needed.
Introducing internal terms or idioms, unless they actually mean something without further context, can make things harder to understand. For example, Rails is described as “opinionated” – which is both truthful and a good description of what to expect later. Whereas saying that Java has “garbage collection” doesn’t really help to understand the language itself. Show people the steps down to the basement by all means, but don’t go 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’re obvious, you should also spell out acronyms)? Yes, because there are firm consequences to 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 the context. Should relational databases be explored? You would have to explain the tables and diagrams a bit, of course. What about “primary and foreign keys”? Try to avoid using the internal term itself initially; start with terms such as “refers to” or an “index of”.
On diagrams and code lists. Obviously, a table is very easy to visualize and draw (which is why it’s such a popular idiom) and you can trivially show both a query and the tables it works with:
FRUIT TABLE
| Last name | Origin |
|---|---|
| Apple | Kazakhstan |
| Banana | Philippines |
| Cherry | Romania |
COUNTRY TABLE
| Last name | Continent |
|---|---|
| Kazakhstan | Europe / Central Asia |
| Philippines | Asia |
| Romania | Europe |
How do I ask SQL which continent the apples come from?
>select fruit.name, nation.continent from fruit, nation where fruit.origin = nation.name and fruit.name=”apple”; +——-+———————–+ | name | mainland | +——-+———+ | apple | Europe / Central Asia | +——-+———+
|
>select fruit.Last name, nation.continent of fruit, nation where fruit.origin = nation.Last name and fruit.Last name = ‘Apple’; +——-+———+ | Last name | continent | +——-+———+ | Apple | Europe / Central Asia | +——-+———+ |
It’s a weak schema and a trivial query, but it shows the purpose and use of SQL, as well as clues to possible problems that you can talk about later if needed. Note that a pair of better formed tables may not act as such a simple example. It’s worth repeating this point – very efficient code can be more difficult to understand than simpler code using familiar structures.
Also, instead of talking about primary and foreign keys, a diagram is more efficient:
Note, however, that there is no reason to limit your example to employees, departments and offices! It is best, of course, to use examples that interest you.
Focus on the journey (and other final tips)
You will naturally use rhetorical devices to persuade your audience of your points.
Comparing products head-to-head is fine for comparing matching products, but much less useful for simply similar technologies. Once chosen, you usually need to use a technology from start to finish — so it’s more useful to show a complete user journey. Comparisons are useful for making elevator pitches (“Sharknado is like Jaws meets Twister”) but from there, focus on the journey. Install it, follow the documentation, try examples. Where did you stumble?
I like to use websites that work as a sandbox for a technology. For example, looking at regex, it was useful to show immediate examples with regexr. Not only does this make it easier to explain – look at my sandcastle! — it also proves that technology is flexible enough to express itself in many ways.
Putting technologies in a timeline (birth, growth, possible death) is a natural way to give context, but it’s even more useful for spotting changing needs and possible embedded issues. “It started before cloud computing” implicitly tells your audience where a new direction might lie.
The last thing I would add reads like long-time advice: don’t be afraid of mediocrity up front. This can be fatal for a pilot, but you probably won’t cause much consternation if your first tech item doesn’t land properly. Try at least a few times before jumping to conclusions.
