Technical writing

My team takes verbatim notes during meetings: as you speak, you see your initials appear in the notes document, followed by an interpretation of what you’ve just said.

Lately, I’ve been noticing how far these two expressions can diverge. Sometimes the gap between what I try to communicate and what others write down is comically (or tragically) wide!

“Hell is other people”, of course, and I can’t change the basics of the human condition. But still, I think there might be a way to improve the situation somewhat.

Realizations

After thinking through it, I realized a few things:

• Speaking succinctly–or, when needed, convincingly–in engineering or product discussions is hard! I need a plan to figure out how to improve. It is not going to magically change on its own.
• My speaking style tends to mirror the way that I write.
• I have written a lot in my life, and spent years reading and writing in a field that some consider to be deliberately obtuse. And I haven’t trained at all on how to communicate effectively in software engineering settings.

So, to work up to expressing myself more clearly in meetings, I thought I would start with clearer writing first–arguably a more important objective anyway, since I spend most of my time using written communications:

• writing code, choosing clear class/method/variable names
• annotating code with comments
• commit messages
• code review discussion
• bug/task trackers

After I improve my writing, then I’ll deal with speaking. (Or more optimistically, I hope that I’ll see improvements in ability to communicate in meetings thanks to improvements in my writing.)

Google’s technical writing course for engineers

To that end, I spent two afternoons working through Google’s Technical Writing One/Two courses. I haven’t done other technical writing courses, but given that this resource is free, relatively quick, and quite useful, I endorse it! I won’t attempt to summarize the course, because you should work through it yourself. But here are some of the highlights:

• Embrace lists, and find opportunities to turn prose into lists.
• Prefer active voice to passive voice. I frequently find myself using passive voice. Now when I spot it, I delete the sentence and start over. If I write a sentence in passive voice, there is a much higher chance that it will be too vague.
• Write short and clear sentences. Use one concept per sentence. Avoid the use of parenthetical (e.g. something like this), as those can easily overcomplicate the sentence or concept you are communicating.

Many of the ideas in the course are seemingly common sense. Even so, I found these concepts worth reading and thinking about: they help me identify patterns, as well as principles underlying those patterns, in my writing.

Next steps

I want to take more courses, but for now, practice is the best teacher. If you know of good resources for improving technical writing and speaking skills, please let me know, and I’ll add to this post.