Writing for Software Engineers: Beyond the Basics

If you’re writing for the internet, the only thing most people will read before deciding whether to click and read your article is the headline. A good editor can help with this and I firmly believe it is their responsibility, but if you are trying to come up with your own headline, a good test is to ask yourself, “Without context, would I read this?”

For example, a title like “The Regulator Will Love You” probably won’t work — what does it even mean? Some better headlines:

“All About Svelte, the Much-Loved, State-Driven Web Framework”

“How TypeScript Won Over Developers and JavaScript Frameworks”

Once your article drops off a website’s front page, almost all of your traffic will likely come from Google searches — and the headline is likely the only thing your reader will see before deciding whether to click on it. Use words in your headline that a reader is likely to search for; note the use of Svelte, web framework, Typescript and JavaScript in my examples.

This would lead naturally to a discussion of search engine optimization, but SEO is such a huge topic that I’m not going to cover it here. Concentrate on making the content as good as you can, and trust that if the content is good, Google will find you.

Tips for Writing Well

Explain Terminology, Spell Out Acronyms

As I mentioned in part one of this series, it is important to consider whether terms might be unfamiliar to your audience and, if so, provide a link or a definition.

A related style point is to be consistent. If you change the name of a variable partway through a method, your code won’t compile. If you change the term you are using partway through a paragraph, the information won’t compile for your readers. So if you’ve called something Protocol Buffers, don’t rename it Protobuffs until you’ve introduced the shortened version: “Protocol Buffers (or Protobuffs for short).”

Likewise, when introducing an acronym for the first time, spell out the full term and then put the acronym in parentheses. Thereafter, you can use the acronym. An exception is if the acronym is commonly known. You probably don’t need to explain RAM or HTML, but you might want to spell out Secure Software Development Framework (SSDF) the first time you mention it.

Keep It Simple

William Zinsser wrote my favorite book on this topic, “On Writing Well,” and it really helped clarify my thoughts on how to write clearly and concisely. I’m deeply indebted to him for the information I’ll share in this section.

A phrase he used that particularly stuck with me is, “The secret of good writing is to strip every sentence to its cleanest components.”

We’re not keen on this as engineers. We tend to make things sound overly complicated so that we can sound frightfully clever and terribly important. Why call a spade a spade when you can call it an “earth-inverting horticultural implement for the purposes of digging”? Why say it’s going to rain when you could say, “We are presently anticipating considerable precipitation”?

The reason to keep things simple is out of respect for your reader.

In technology, in business more broadly and also in politics, words are frequently used to impress or obfuscate rather than explain. Companies that go bust find themselves with “a negative cash-flow position,” or the plane didn’t crash, it “underwent an involuntary malfunction,” and so on.

Don’t do this. Look to write as cleanly as you can, in the same way you might for a method in your code.

For nonfiction writing, your goal shouldn’t be to show off how wide your vocabulary is, but to try and convey meaning as clearly as possible. This is hard work; a clear sentence is not an accident. People who appreciate good writing will understand the work that went into crafting it.

I have a particular weakness for overusing qualifiers. Cut these out. Rather than saying, “Some people have suggested that Kubernetes might be considered overly complex in certain situations,” say “Kubernetes is complex.” As Zinsser put it, “Good writing is lean and confident.”

Cut out small words. I found it “a bit” confusing; I was “somewhat” irritated. Be confused, be irritated. Avoid “effortlessly easy” — if it was easy, it was effortless, so use “effortless.”

Prune your adjectives — most are unnecessary. You don’t need to tell me the daffodils were yellow or the soil was brown; I can guess. Of course if the soil were blue, that would be more noteworthy.

If something is worth mentioning, make it interesting to read — don’t tell me it’s interesting; show me.

Make Your Text Inviting to Read

Writing is a visual medium — it catches the eye before it has a chance to get to the brain. Short paragraphs make what you write look inviting, whereas a long chunk of type can be off-putting.

There is a tradeoff here, of course. A succession of tiny paragraphs is as annoying as a paragraph that is too long. I’ve edited pieces that were entirely made up of one-sentence paragraphs. Avoid this. I would say a good default is around three sentences for newspapers, and around four or five for blogs. But vary the length.

Within each paragraph, watch out for sentences that are too long. If you find yourself hopelessly lost in a long sentence, you are probably trying to express too many thoughts. A quick way out of this is to split it into two sentences, or even three.

See if you can add variety by reversing the order of a sentence, substituting a word that is fresh or unusual, or altering the length of your sentences so that they don’t all sound the same.

Sometimes the best way of tackling a tricky sentence is to get rid of it. This always seems to be the last option you think of; if you find yourself wrestling with rephrasing or clarifying a sentence, you might be better off without it.

Stylistic devices such as rhythm and alliteration are helpful. For this reason, I encourage you to read out loud whatever you write. I write entirely by ear and read everything aloud before I publish it.

Use Available Tools

In part one, I mentioned my software toolchain (Mac Pages—> Google Docs—> Docs to Markdown). I generally edit HTML and Markdown in a text editor but will sometimes resort to Dreamweaver or Caret. I don’t do much image work, but I use Pixelmator Pro for illustrations.

I usually conduct interviews remotely on Zoom. By using its built-in audio recording, I don’t need to rely on my terrible shorthand. For in-person interviews, for example at a conference, I carry a Zoom H4N Pro, which I’ve had for years; it’s a great product, but you might get away with just using an app on your phone.

As technology can fail, I also run a backup recording on my phone. I still transcribe quotes from interviews by hand but many writers use a voice-to-text transcription service such as Otter or the human-backed Rev to take the grunt work.

I think most writers today are looking at large language models (LLMs) and wondering if they might be useful. I have experimented with them, but haven’t found them helpful since the text they produce is too generic and error-prone — the writing equivalent of Muzak or, as consultant Mark Hurst puts it, Polyfilla/spackle.

Given their shaky ethical ground, environmental cost and the dangers of hallucinations and plagiarism, I consider LLMs more of a risk than they are worth at this point and won’t use them at all in my writing. The New Stack doesn’t use artificial intelligence (AI)-generated articles, and has published its policy on this, which is worth reading.

Software aside, the main tools for any writer are a good dictionary and a thesaurus, and you might find a grammar guide helpful. Alongside Zinsser, I’d also recommend reading “Writing for Story,” by Jon Franklin, and “Eats, Shoots & Leaves,” by Lynne Truss. During the first Covid lockdown, I did Neil Gaiman’s Masterclass on the art of storytelling with my eldest child, an aspiring novelist, and we both thoroughly enjoyed it.

I don’t have time to get into SEO matters here, but if the subject interests you I found “Marketing in the Age of Google” helpful; it is a little out of date now but the core advice is solid. The definitive SEO guide is “The Art of SEO,” by Eric Enge, Stephan Spencer and Jessie Stricchiola.

I strongly recommend that if you find a writer whose work you admire, see if you can imitate their style; you’ll learn a great deal from playing with other writers’ techniques.

Ultimately, writing, like coding, is a form of problem solving. The challenge might be with obtaining facts, organizing the material, or tone or style. Some patterns and structures can help but, as with programming, you’ll get better with practice.