Writing for Software Engineers: A Primer

READMEs. User manuals. Operation guides. Handbooks. Command-line help. Internal chat. Company blogs. As software engineers, we write often, and in many different contexts. The code we write often doesn’t provide value without some sort of writing to accompany it. Most organizations provide engineers support for getting better at writing code, usually in the form of training or mentoring. Few, however, provide this same support for getting better at writing text. Why is this?

I’m going to argue that this lack of support comes from viewing people as static instead of as dynamic. This severely limits the impact of the work people can accomplish in your organization. What do I mean by static vs dynamic? Let me explain by organizing some statements you’ve probably heard before:

static dynamic
We shouldn’t be putting engineers on sales calls; they don’t know how to talk to prospects. If we put engineers on sales calls, they’ll better understand the problems we need to solve.
We need Jill heads-down on implementing the backend for the new project. Don’t distract her with writing a blog post. Jill has expressed interest in improving her writing skills. She’s been working on that feature, so let’s have her write about it.
I didn’t get the right feeling from Jack during that product demo. We need to hire a sales engineer to do those from now on. Jack had some trouble answering questions in the last product demo. Let’s talk with him and figure out how we can improve.

The static solution to problems that stem from inexperience is to revoke the invitation to participate and try to find someone more suitable for the job. Aside from being really expensive, this static attitude towards people and what they can do causes resentment and poisons cross-functional collaboration. Often when expressing a static viewpoint, people will use certain language to show that they are acting in the best interest of the person in question. “I didn’t get the right feeling”, “They don’t know how”, “Let’s not distract her”. The less specific, the better. The irony here is that the person “being helped” is often not consulted on what is best for them. Viewing a person as static, and acting accordingly, is never in their best interest.

The dynamic solution to problems that stem from inexperience is to engage with people that want to learn and set in action a plan for how they can improve. A organization that can learn is not created by a top-down mandate; it is formed by how people react to things that didn’t quite go the way they wanted them to. Is this an opportunity to do better? Great, let’s talk about how to improve. Or is failure a vindication of what you knew all along? Letting things slide into failure is not a bargaining chip.

What does this have to do with learning how to write better as a software engineer? And what does writing better even mean?

I talked about static and dynamic attitudes because there is a good chance that as you try to grow your skills as a writer you will run into static attitudes from your colleagues. “You’re paid to write code, not text.” People with engineering backgrounds tend to think that writing code is more valuable than writing text; coding is where all of your time should be spent. People with non-engineering backgrounds tend to think that engineers’ brains work differently than the rest of the human race; coding and writing are exclusive skills. Neither of these assumptions are true. Recognizing static behavior is the first step in exposing how damaging it is to your organization. I’ll talk more about strategies for dealing with static behavior in a future post.

Writing better means giving your intended audience the information they need in the format they find most accessible. Your intended audience should be clear and unambiguous before you start writing. Sometimes you will have several audiences. This is often a challenge for engineers learning to be more effective writers. We know DRY is a good thing and we try to satisfy all audiences so we don’t have to repeat ourselves.

An example. Your operations and security audiences need roughly the same information but operations prefers a handbook with lots of deep-dive technical detail and security prefers an overview with system diagrams. Writing up a lengthy document that provides both formats is less accessible for both audiences. Instead, focus on providing the best experience for each audience, even if it means that you need to repeat yourself in different formats.

Your audience will tell you if you are or aren’t meeting their needs. Active communication with your audience is the most efficient way to get this feedback. Don’t shy away from sharing rough drafts with external stakeholders (customers). The worst thing you can do is spend a lot of time making a document perfect, only to hear from your audience that they don’t understand it. Your colleagues can be a great source of inspiration, but their opinions should never supercede the opinions of your audience. Lastly, outlining what to write can be a team sport, but writing by committee often fails to meet expectations.

“Few things in life are less efficient than a group of people trying to write a sentence. The advantage of this method is that you end up with something for which you will not be personally blamed.”
—Scott Adams, creator of Dilbert

Thanks for reading. I’ll be writing more about improving writing skills as a software engineer in future posts. Are there certain topics you’d like me to cover in more detail? If so, let me know in the comments wherever this is posted.


Now read this

Debugging code for the Particle Core/Photon

I’ve been spoiled as a software engineer. When I write Python, Ruby or Javascript I have a REPL to try different ideas out. I can set breakpoints in PyCharm, RubyMine or the Chrome Devtools to inspect my stack at any point. The feedback... Continue →