When I was in elementary and secondary school, I did not enjoy reading or writing. Both were a chore. This probably had a lot to do with the fact that the rote learning and clerical curriculum that is core to modern, institutional education, was just not right for me. I enjoyed exploring ideas and argumentation, but not, for the most part, through reading or writing.

One of the few exceptions during this time, was my English class in grade eleven. As I look back on this class, it probably made more of a lasting impression on me than any other class that I took in high school. The teacher was a bit of a rebel in the eyes of her colleagues and she certainly was not everybody's cup of tea, but many of my high-school friends feel a similar, lasting impression from this class.

The focus of the entire semester was on writing a well-structured, well-reasoned, three-part essay, first, analyzing a theme from the novel The Lord of the Flies, then repeating this exercise for a novel of our choosing.^[1] We wrote a similar essay based on a short story as an introduction to the semester, and we had to squeeze in a brief study of one of Shakespeare's works to satisfy Provincial curriculum requirements, but because we focused the rest of our time on, essentially, two essays—living with our work, revising it, analyzing it from different perspectives, reworking it, evolving it, perfecting it—this had significant appeal to me and I learned a lot more because of it. I was not just completing assignments, memorizing facts, jumping through hoops, or ticking boxes—the rote learning typical of most classes—I was exploring, crafting, and perfecting my own work, thoughts, and ideas.

In my last year of university, and especially into graduate school, when learning became much less about memorization and repetition, and more about exploring ideas through experimentation and practical application, I started to enjoy reading and writing a lot more. In graduate school, I read a lot and wrote a lot. I discovered LaTeX, and I started to appreciate technical writing, complete with mathematical equations and figures, that was nicely formatted and pleasing to the eye. I was also fortunate that my thesis advisor was a good technical writer and I benefited a lot from his repeated review of my 150-page thesis, as it evolved. After graduation, when I started working, I began devouring books—from philosophy, psychology, economics, neuroscience, behavioural science, management, along with many technical books related to my work—benefiting, at the time, from at least an-hour-a-day to read on my commute to work by train.

I particularly enjoy long-form writing, as it allows me to explore and connect ideas consistently and holistically. After I started publishing my writing on this blog, over four years ago, I have paid more and more attention to improving my writing.^[2] With so much of our technical communication being written—from documentation, to email, team chat, code review comments, tickets describing our work, blog posts, and so on—being effective at clearly communicating technical subjects, in writing, is exceptionally beneficial to our careers. I am not going to claim that I am the best technical writer—it is something that I want to continue to get better at—but, in this article, I want to explore some techniques that I have adopted to become better at technical writing, and suggest that these considerations might improve your technical writing as well.

The Oxford Comma

For years, I never paid much attention to the correct use of commas. For some reason, I never ended up with the teachers who emphasized grammar or punctuation. As I wrote more in graduate school, I came to appreciate the importance the comma, especially in technical writing. Using the comma effectively is probably the single most valuable thing that you can do to improve the clarity of your technical writing. It will make your writing easier to read and more appealing to others, making it more accessible, requiring less effort to understand.

Lynne Truss, in her book on punctuation, Eats, Shoots & Leaves, states:

Proper punctuation is both the sign and the cause of clear thinking.

What a wonderful, aspirational thought for our technical writing. However, she also acknowledges that the comma can be a bit tricky:

No wonder feelings run high about the comma. When it comes to improving the clarity of a sentence, you can nearly always argue that one should go in; you can nearly always argue that one should come out.

In a technical-writing course in university, I learned that when enumerating a list, the comma before the final item is optional. For example, "one, two and three" compared to "one, two, and three".^[3] I had never heard of the Oxford comma until my good friend, while reviewing my resume, suggested that I use it more liberally, to clarify the dense presentation of technical information, typical of a resume. Ever since his suggestion, I have paid a lot more attention to the Oxford comma, and now I use it religiously. It is one of those things that once you appreciate its value, it is hard to unsee. It really bothers me now when I read a text that does not use it.

The Oxford comma—which is also known as the serial comma, or series comma, and gets its name because it is used by Oxford University Press editors—is the final, optional comma in a list of items. It is somewhat controversial, but I find that, especially in technical writing, it provides clarity, removing any ambiguity about the number of items in a list.

In Eats, Shoots, & Leaves, Truss describes how she argued for the Oxford comma in the following passage regarding punctuation marks, because without it, this is a list of three instructions, not four:

They tell us to slow down, notice this, take a detour, and stop.

The Oxford comma recently received some attention in a legal case regarding overtime pay. Consider the following paragraph:

The canning, processing, preserving, freezing, drying, marketing, storing, packaging for shipment or distribution of: 1) Agricultural produce; 2) Meat and fish products; and 3) Perishable foods.

Because there is no comma after the word "shipment", it is unclear if "distribution" is separate from "packaging for shipment", or if they are one activity.^[4]

In technical writing, especially when enumerating non-trivial lists, I prefer to avoid all ambiguity and I always use the Oxford comma, or I restructure the sentence to remove the ambiguity in the first place.

Hyphens

Technical writing is necessarily dense with technical terms. In addition, as we strive to be precise with our language and descriptions, we end up using a lot of qualifying adjectives. As a result, these sentences can become very difficult to read. As I just described, the careful use of the comma is essential for the reader's understanding, but technical writing often needs some help from the hyphen as well.

In general, people do not use hyphens enough—they are too-often overlooked. In her book Eats, Shoots & Leaves, Truss provides some hilarious examples that are ambiguous without a hyphen: extra marital sex, little used car, superfluous hair remover, the pickled herring merchant, and the two hundred odd members of the Conservative Party.

The hyphen can be especially important in technical writing, providing clarity and making dense technical-phrasing much easier to read. This is something that I wrote about previously in my article on Making Your Resume Stand Out From the Crowd. A resume is an especially compact form of technical writing and it is important to remember that you are probably a lot more familiar with the terms and topics that you are writing about than the reader is. The example that I provided in that article was:

While describing "the time series database for an Internet of Things streaming data application" might read well to you, "the time-series database for an Internet-of-Things streaming-data application" reads a lot better to me.

Similarly, statements like "the feature-rich time-series platform", or "the real-time monitoring and closed-loop control of distributed, renewable-energy assets", benefit greatly from the addition of a few hyphens.

Once you start obsessing over the use of hyphens in your own writing, and lamenting the lack of hyphens in much of the technical writing that you read, you will certainly appreciate this quote from the style manual of the Oxford University Press:

If you take hyphens seriously, you will surely go mad.

The Em Dash

For me, the most appealing punctuation mark in technical writing, especially long-form technical writing, is the em dash. The em dash is extremely versatile. It can be used in place of a comma, a semicolon, a colon, or brackets.^[5] Interestingly, the em dash is not an essential punctuation mark—the way periods or commas are—and you can, of course, get away without it—and most people do.

Part of the appeal is that the em dash has a somewhat loose definition and it is certainly harder to use incorrectly. I like how the em dash is less formal and more conversational than other punctuation, like the semicolon. In addition, I find it more visually pleasing—less abrupt and easier for the eye to follow. But the thing that I like the most about the em dash is that it "invites the aside in", as Truss notes in Eats, Shoots & Leaves. It is useful for both narrowing and expanding a train of thought, and including information that might lose momentum in a new sentence.

As we strive for precision and accuracy in our technical writing, ideas often require a lot of clarification and qualification. This can lead to long sentences, and passages that are hard to follow. Supporting-information can be included using commas, but too many asides using commas—especially in a sentence that has other commas—can become hard to follow. The em dash provides a clearer delineation for these asides. Supporting-information can also be included parenthetically, however, I usually find this approach to be too much of an aside. In technical writing, asides are often not just auxiliary information, but, rather, contributory, complementary, supportive, or elaborative ideas, that are vital for establishing or clarifying the main idea. I use the em dash to incorporate all of the ideas that I feel are essential to the sentence. Unlike including information parenthetically, the em dash is great for adding clarity to a sentence, while, at the same time, giving the supporting-information as much importance as the central idea of the sentence itself.

The following is an example, from my essay reflecting on my use of quality views, of me using an em dash to highlight a central aside within a sentence, as well as connect two sentences together:

In fact, the key example in my original blog post—highlighting the moment when I knew quality views were an effective technique—was when I had a valuable discussion of the risks associated with a poor-quality, legacy component—a component that we chose not to invest in improving.

I could have written this passage as follows, but I find the aside less clear and the semicolon abrupt:

In fact, the key example in my original blog post, highlighting the moment when I knew quality views were an effective technique, was when I had a valuable discussion of the risks associated with a poor-quality, legacy component; a component that we chose not to invest in improving.

And, no, using a dash-like this-or even two dashes--like this--will not do. It is no replacement for the use of a proper em dash.^[6] I do not like spaces before, or after, an em dash. When used without spaces—like this—it looks elegant; when used with spaces — like this — it looks less appealing. It is handy to know, especially when writing in Markdown, that in HTML, an em dash is denoted by &mdash or, equivalently, —.

I almost always use an em dash where a semicolon could otherwise be used to connect two ideas, like in the example above. The one place that the semicolon remains critical, is for enumerating lists. What follows is an example from my series From a Time-Series Database to a Key Operational Technology for the Enterprise demonstrating the use of a semicolon for delimiting items in a list:

I am assuming that the time-series database supports the efficient storage and query of time-series data; that it can perform server-side aggregations; that it is scalable to millions of series; that it is fault tolerant and supports models for workload distribution and disaster recovery; and that it is easily deployable on cloud-native infrastructure-platforms.

Like the Oxford comma, once you appreciate the effective use of the em dash, it is hard to unsee. It is also easy to fall in love. I can relate to what Adam O’Fallon Price writes in Regarding the Em Dash:

In truth, I probably overuse the em, find too much pleasure in asides, in explanation.

However, as Adam concludes, it is in support of communicating clearly, which is of utmost importance in technical writing:

Yes, we want to communicate clearly, but sometimes, just as crucially, we also want to clearly communicate the difficulty of communicating clearly.

Formatting

I do not want to say too much about formatting, since there is a lot that can be said, but there are a couple of things that are particularly important to me, especially in technical writing.

The first is an outdated rule that too many people still follow: delimiting adjacent sentences by inserting two spaces after the period. This rule is a holdover from when we used typewriters with monospaced font—the extra space was favoured for readability. However, when we are using proportional typesetting—which is pretty much always—the second space reduces readability, rather than enhances it. I detest two spaces after a period. My eye is drawn to it. The writing can be brilliant otherwise, but the addition of this extra whitespace will spoil it for me. I find it very distracting. Please do not put two spaces after a period, unless you are still using a monospaced typewriter.

The second is consistency. Consistency in technical writing is really important to me. If you are going to refer to variable names and format them with a monospaced front, then do it consistently. It drives me nuts when I see a variable referred to as status and status in the same paragraph. It drives me even more crazy when it happens in the same sentence. If you are going to refer to the Time-Series Database Service as a proper title, then, do not also refer to it as the Time-series Database Service, or the Timeseries Database service. Similarly, for names like Service API. If Service API is the proper title, then do not also write ServiceAPI, Service Api, or Service-API. If you include a bulleted list of proper sentences, capitalize each one and consistently end each sentence with a period.

Part of my desire for consistency is just aesthetics—I want technical writing to be consistent, beautiful, and pleasing to the eye. Part of it comes from understanding that our technical writing is also a reflection of our technical work. If your technical writing is full of formatting errors and inconsistencies, then why should anyone think that the software or engineering work that it describes is any different?

As I already mentioned above, in Eats, Shoots & Leaves, Truss notes that, "Proper punctuation is both the sign and the cause of clear thinking". I include pleasing and consistent formatting in the same category.

Editing

I have received a number of compliments on the quality of my writing, especially its clarity and simplicity for extremely technical topics. I do think I have a knack for distilling technical topics—through my experiences and through observing the experiences of people around me—and presenting them in simple and practical terms. But do not be fooled: the essays that you find on this blog are the result of hours and hours of research, composition, and editing—reading, modifying, rereading, questioning, debating, reviewing, revising.

I pay a lot of attention to the quality of my writing. The more I write, the more I also appreciate the writing styles and techniques of others—their use of punctuation, their choice of words, their attention to formatting, their juxtaposition of long and short sentences—influencing and incorporating these techniques into my own writing. Like many things, the more you practice, the better you get. As you pay attention to it, you will find that your writing evolves with you, over time, subject to your influences.

I think there is something to be said for the quote often attributed, probably inaccurately, to Ernest Hemingway: "Write drunk; Edit sober."^[7] I do write the majority of my blog posts while sipping a beverage on the patio, or in my favourite pub (this is usually a different story for my technical writing at work, of course). I do find that when I am trying to get my initial thoughts down, it is easier, and more fluid, relaxing with a drink or two. I find the most important thing, however, is to separate writing and editing, respecting them as two distinct activities, that require very different mindsets, engaging different parts of the brain.

I used to reread what I had previously written as a way to get back into context—especially the introduction, which is usually the section that is the hardest for me to write and the section that I revise the most—but this would, inevitably, lead to a lot of editing of what I had already written, or thinking of how I might structure what comes next, rather than actually writing anything new. It made for very slow progress.

Some of the best advice that I have received (I cannot, unfortunately, recall the source of this advice) was to keep writing and editing separate—along the lines of the write-drunk-edit-sober quote. Now, before I start writing, I explicitly decide if this will be a writing session, or an editing session, and I try and keep the two distinct. It has helped me write faster, although, I am still, and will likely always be, a very slow and deliberate writer, exploring and weighing many threads of thought in my head along the way. During a writing session, I try and make progress writing the next paragraph or the next section, ignoring the fact that some items might be repeated, out-of-order, or incomplete. I focus on getting my ideas down and leave structuring them more effectively to a session dedicated to editing. This approach has improved my productivity.

On a day that I start writing something new, or I return to something that I have not been working on for a while, it takes me some time to structure my thoughts and write productively. It takes me a day to "fill up the cache", so to speak, writing more naturally in the days that follow, a phenomenon that Bjarne Stroustrup, an author and the creator of the C++ programming language, also describes. A technique that I find helpful is to leave my writing in a place where it is easy to pick up again and get back into a state of flow, like leaving a sentence half finished. This is technique that I wrote about in my essay Be More Productive By Not Finishing Your Work.

In my opinion, the single most important thing that you can do to improve the quality of your writing is to edit it over time. There is nothing better than writing something only to come back to it after a few weeks, or a few months, with a fresh perspective. When you are actively writing, all of the ideas are swirling around in your head and it is too easy for your brain to anticipate what you are reading, glossing over it. When you review your writing sometime later, you read it from a fresh perspective, more from the perspective of someone new to it. You will find errors that you missed before, passages that lack clarity, passages that need restructuring, and superfluous sentences that can be discarded. Whether or not you have the luxury of time, reviewing your writing in different contexts can also really help improve the quality. Do not just review what you write in your editor. If you write in Markdown, review in HTML. If you write in LaTeX, review in PDF. If you write in the afternoon, review in the morning. Review in a different location, or on a different medium, like your phone, or a tablet. The simple act of changing contexts really helps you see your writing from a fresh perspective.

Finally, having an editor will really help improve quality of your writing. My wife regularly reads my essays and helps me edit them. I am very thankful for her perspective and expertise. For the more technical articles, she is generally just reading for obvious errors, but she does tend to enjoy the more personal and non-technical articles that I have written, like my Reflections on Being a Team Lead or The Importance of Agency. I find that I tend to gloss over small errors in sentences, especially after I have been absorbed in the same essay for hours or days, and she is much better than me at spotting a mistaken "form" instead of "from", or "steam" instead of "stream"—two mistakes that I make often enough that I actually look for them myself now. No matter how many times I proof-read one of my essays, she can usually still spot at least one error.

Conclusion

It might be nice to think that you can just run your technical writing through a linter, like source code, to produce wonderful formatting and structure, but your writing reflects too much of your personal style to embrace this kind of uniformity. Even when it comes to punctuation, in the book Mind the Stop, G. V. Carey defines punctuation as being governed "two-thirds by rule and one-third by personal taste".

I agree with Bjarne Stroustrup that it is important to hear the author's voice in their writing and that speaking about what you are writing about can help improve your writing:

When I read a book, I really feel that if I can hear the author's voice ringing in my head—complete with weird accents and peculiarities of their speaking patterns—then I feel like something has succeeded. If it feels like dry, academic text, somebody has written yet another dry, academic text. And so, giving talks about the subject really helps. And, for many people, ... I can hear them when I read it, and that is good.

My hope is that you found my perspectives on technical writing in this essay useful and that it inspires you to refine and improve the quality of your own technical writing.