Writing for Software Engineers: Read Me First
Many of us engineers suffer from a common affliction: fear of writing. It often starts at school where we are told we don’t have a “gift for words.” This is nonsense. Writing is a craft, and the principles of it can be learned.
There are several reasons why you might want to.
As more of us shift to remote and hybrid working, the ability to communicate clearly in written form becomes more essential than ever. Writing can be a brilliant way of building your personal brand, and in the process it forces you to learn and develop.
Sharpening your writing skills can also help you advance in your career. If you aspire to work in management or developer relations, want to establish yourself as a conference speaker or even dream of authoring a book for a tech publisher one day, writing (and the previously mentioned brand-building) is central to achieving those ambitions.
Moreover, it gives you a reason for talking to other knowledgeable people, and it is stimulating and interesting and hard. And I think, as engineers, we are drawn to hard problems.
There are also some striking parallels between writing and programming. Some are obvious. As with programming, you get better at writing with practice. As with programming, you often learn new writing techniques through imitation. And as with programming, writing has patterns that can be useful, but those patterns are also seductive, beguiling and tempting to overuse.
Your subconscious mind also does a lot more writing (or programming) than you might think. You can spend a whole day wrestling with a problem in an article — or with a piece of code, only to figure it out immediately after taking a break.
I firmly believe that engineers need to get better at sharing our knowledge, and writing articles is a key way to do this. As someone who has worked as an engineer and as a CTO and now predominantly makes a living as a writer and adviser, I’ll share my approach in the hope that it might encourage some of you to share more of your knowledge.
With this in mind, I’ll start by breaking down my writing process. Of course, everyone’s creative practice is a little different. But thinking about how someone approaches the work can be a helpful starting point.
Starting the Writing Process
I like to start by thinking about who I’m writing for. I find it helps to have a definite person in mind before you start. One of the things this does is allow you to answer questions like, “What do they know?” and “How much do I need to explain?”
As an example, you might think, “I’m writing this for a senior developer who is stepping into their first leadership role. They’ve likely been coding professionally for around seven or eight years, but haven’t yet led a team.”
Or, “This is for a junior developer — perhaps first or second job — working on their first project with AWS Lambda. They know Go, having learned it at university, but they don’t know much about how to structure a Lambda project.”
Of course, “This is a post for someone like me from two to three years ago before I knew this stuff” is also a good (and common) starting point.
One reason for knowing who you are writing for is it can help you identify unfamiliar terms to some or all of your target audience. If a term is unfamiliar you can either:
- Link to a good explanation (don’t reinvent the wheel).
- Provide a brief definition if you can’t find a good link.
If you have a lot of terms like this, providing a glossary is a good option.
Once I’ve decided who I’m writing for, I decide what role I’m playing for that reader. Am I a reporter? An educator? Just an average programmer?
And then I ask, “How much do I want to cover, and what one thing do I want to say?” This matters, because all writers have a desire for completeness and precision. My best advice here is to think small. Decide which tiny corner of your subject you are going to cover and aim to do so as well as you can.
The next question I ask myself is, “What kind of writing is this going to be?”
As a default, I suggest setting yourself a word budget. As an example, 500 words is a good number for announcing a new tool or product and briefly describing what it can do — essentially, a news report. For a blog post or similar, 1,000 to 2,000 words is standard. Tutorials, especially if they have a lot of code samples, and written interviews or profiles might run a bit longer, but always aim for concision.
If an article ends up being really long, consider if it can be split into two or more parts. Note, however, that the internet is full of part one articles for which part two never appears, so try and write the whole thing before you publish the first part.
Making Other Upfront Decisions
There are some other decisions that you need to make upfront. One is, are you going to write in the third person (as an observer) or in the first person (as a participant)? A related question is what tense you are going to use; most people will write mainly in the past tense (“I tried to write in Go the other day”), but you could experiment with writing in the present (“I’m sitting on a jet to San Francisco while hacking away at some Go code”).
Whatever you decide, stick to it. It’s jarring for the reader to go back and forth between perspectives and verb tenses in a single piece.
Another good thing to consider upfront is whether you’ll need to conduct any interviews. For your own blog, and often for a corporate blog, you will be expressing an opinion. For an outside publication, you are more likely to need multiple sources and to conduct interviews for quotes. Maintaining a network is extremely helpful here so that you have contacts you can readily reach out to.
Before conducting any interviews, I will normally write a rough first draft so that I can work out what gaps I want to fill. Then I’ll preplan questions before I reach out. The interview is a mixture of preplanned questions and ad hoc conversation, but I find that planning is essential for good results.
Interviews can be conducted over email, online via a conference platform like Zoom or in person. I used to favor email, but as I got more experienced, I started to prefer doing interviews by video call. Rather than scramble to take notes by hand, it’s wise to record video or phone interviews — with your subject’s permission — and several artificial intelligence (AI)-fueled applications can provide voice-to-text transcriptions, making it easier to quote your sources accurately.
Writing Your Draft
If my experience as an editor is anything to go by, writers seem to get oddly attached to their first draft. Try not to. Instead, think about your first draft as exploring your problem domain by whichever method works for you, rather like writing test cases first, or drawing UML diagrams.
As you start to write, you’ll often find that material flows in a direction you didn’t expect it to, and maybe some of the upfront decisions you made weren’t the right ones. That’s OK. Let the material take you where it wants to go, then review and refine it later.
When I start a piece, I don’t think very much about where I’m going with it. I find blank pages intimidating, so I tend to throw words at the screen or piece of paper without thinking too hard and then shape them once I’ve got a rough draft.
I’ve also found I write quite differently if I’m writing in longhand versus typing on a screen. I normally work at a computer but I think it’s worth trying both and seeing which works best for you. I’m dyslexic, so I’ve also tried writing via dictation, and the results are never very satisfactory for me, but your mileage may vary.
You need to get good at throwing material away. I often find I end up deleting the first two or three paragraphs of the first draft because they’re not good enough; Heather Joslyn, The New Stack’s editor-in-chief, calls these disposable paragraphs “throat clearing,” which I love. You’d be surprised how many articles I edit where I end up discarding the first few paragraphs as a starting point.
I draft in Pages, partly because I use a Mac and partly because I find it unobtrusive, but mostly because I know I’ll submit the article somewhere else — typically in Markdown, HTML or a Google Doc, depending on the publisher. This is analogous to doing a throwaway prototype for an application, which we don’t do much in reality but can be useful.
In his Masterclass on the art of storytelling, the author Neil Gaiman says that “doing your second draft is the process of making it look like you knew what you were doing all along.”
I generally move to Google Docs for the second draft since it supports tracked changes and versioning, which is helpful for editing, allows comments and is great for collaboration. The open source Docs to Markdown plug-in, while not entirely bug-free, generally does a great job of extracting text from Google Docs into HTML and Markdown, depending on what is needed for your content management system.
The second draft is where I start to think about the structure for the piece, and whether it flows logically. This is where knowing who your reader is really starts to pay dividends since you can ask yourself questions like, “What would this person want to know first?”
If I’m working without an editor I get someone else — usually my long-suffering wife — to read my second draft once I’m happy with it. If I’m working with an editor then I usually send the second draft to them.
I usually send the draft to anyone I interviewed to make sure they are happy with their quotes before I publish or submit. It helps nurture contacts for future interviews and helps prevent lawsuits. I’ve also often received helpful feedback this way; I’ve only once had major problems with an interviewee wanting extensive changes.
Understanding Writing Patterns and Structures
If you read the “Gang of Four” design patterns book at an impressionable age then found yourself putting factory methods and decorators all over your code, you’ll be familiar with one of the problems with patterns: they are useful, but it is tempting to overuse them.
Formulaic writing has a poor reputation, but journalists, in common with all writers, sometimes rely on tried and tested patterns, and I think it does no harm to learn a few.
The Inverted Pyramid
The inverted pyramid is one of the most widely used writing patterns. It is commonly used in news, but has wide application across other kinds of text, including blogs, editorial columns and marketing factsheets.
Think about it as a descending hierarchy of importance. You start with the most newsworthy facts, then follow with paragraphs of supporting material, getting into deeper background details as you continue further down.
The key to making this structure work is the opening paragraph, which should outline the most important information clearly and concisely to pique the reader’s interest.
Within this structure, the most important sentence is the first one. If your reader doesn’t decide to read the second sentence, your article is already dead. The trick is to write so that each sentence acts like a hook that draws the reader on to the next sentence to try and encourage them to read all the way to the end.
Here is an example of a news lead from Darryl K. Taft, The New Stack’s news editor:
“Despite the recent hubbub about Microsoft diminishing its use of its C# programming language in favor of the Rust language, Microsoft says it remains committed to C#.”
You learn a great deal from this one sentence. You learn that there has been a great deal of chatter that Microsoft is abandoning C# for Rust, and can likely infer that Microsoft is using more Rust for its own projects. You also learn that Microsoft is sufficiently concerned about the noise that it has issued a public statement denying the rumors.
The Hourglass
Narrative writing is often used for newspaper and magazine features. A narrative has two components: a story and a storyteller. A storyteller writes more like a playwright or a novelist — depicting people interacting with one another within vivid surroundings. It isn’t often used in technical writing, but it can be an effective way of writing a case study, for example.
A challenge with writing this way is that you can lose sight of the news story you are trying to tell. The hourglass pattern, usually credited to Roy Peter Clark, a journalist and writing coach, is intended to combine the strengths of the narrative and inverted pyramid styles.
The hourglass story has three parts:
- An inverted pyramid that summarizes the newsworthy information at the top.
- A narrative, which allows the writer to develop the story in depth and detail.
- The turn or pivot, which marks the transition between the two formats.
The Focus Style
The Wall Street Journal has used the focus style for years, often for its front-page features.
Like the hourglass, the broad goal of the focus style is to try and combine narrative storytelling and news writing styles. It has four parts. The first is the focus lead, which unlike the lead for the inverted pyramid, might be as long as five paragraphs. The second part is the nut graph, which gets its name from summing up the story “in a nutshell.” The nut graph states the central part of the story and how the lead illustrates that point.
The body of the story then develops the central point in detail, and the kicker brings the story to a natural conclusion with a memorable twist or remark. My article “Avoiding ‘Success Disasters’: Ticketmaster vs. Taylor Swift” shows how this works, with the nut graph appearing in paragraph five, outlined in red below.
A slight variation on this style, often used when writing about technology, is an anecdote or story providing a hook and lead, and then the nut graph acting as a stylistic turn before getting into the meat of the article. Partly this works because humans are naturally drawn to stories; this is also effective in conference talks, which is why the majority of TED Talks open with an anecdote.
In “A Technical Guide to Burning Down a Troll Farm” from Jennifer Riggins, you can see how it works. She opens with three paragraphs of narrative focus (shown with a red border below) before the nut graph acts as a turn in paragraph four.
Knowing When to Stop
The term “kicker” refers to the ending of the story. Endings cause endless problems. I think one of the reasons for this is that at school we’re taught that essays have a beginning, a middle and an end, and that the ending should restate what we’ve already said in a more compressed form.
You’ll know you are doing this when you put “Conclusion” in a subheading, or write something like “To sum up, it can be noted that … .” At this point, your reader will hear your entire article creaking.
A conclusion like this undermines any good work you’ve done up to this point. A good ending should feel like a natural place to stop. One trick I use is to go back through my notes and see if I can find anything that feels like a natural reason to bring the piece to a close. Here is an example from my The New Stack article “All About Ecstasy, a Language Designed for the Cloud.”
“We’re about six years into this, and we’re just now building the actual project we intended to build,” Purdy said. “It’s the longest road to a minimal viable product you’ve ever heard of!”
Now that I’ve covered the basics, check out the second part of this series for tips on refining your work and getting attention from readers.
