At DevOpsDays Berlin 2022, I was slated to give a 30-minute talk titled Writing Professionally. Unfortunately a positive Covid test just three days prior to my departure threw a wrench in those plans, and I was unable to travel or attend a conference (much less speak at one, unmasked).

So, I am converting my talk into a write-up, before any symptoms set in.

Writing Professionally (in English)

This is a talk about developing superpowers. Superpowers that will help you be better in any role, any industry, any profession — particularly the ones where you work in distributed teams, and use an asynchronous and distributed workflow.

This is about expressing yourself clearly, succinctly, and professionally in writing. I have put this together for the English language, though parts of this talk may be applicable to other languages as well.

This is about writing well in a professional context. That means we’re not talking about poetry, or creative writing, or writing a message to a friend. We’re talking about writing in the context of professional communications.

Being understandable

When you write in a professional context, your goal is the reader (or readers) understanding you.

That is really the overarching goal, and it’s important to understand that we must do everything we possibly can to make it easy for our reader to understand what we mean.

When you’re writing a novel, you can add plot twists and surprises. You can even use a literary device called an unreliable narrator, where at the very end of the novel you reveal that everything the narrator said (or the protagonist did) was a lie, a delusion, or a dream.

In professional writing, we don’t have that luxury. We must write in such a way that whoever reads our writing, understands us.

And that is the overarching goal no matter the mode we use to communicate. Writing to be understood extends to

• email messages,
• chat messages,
• issue descriptions and comments (in whatever issue tracker you might be using; this includes Jira tickets, Trello cards, GitHub issues and the like)
• collaboratively edited documents (like wiki pages or shared Google docs)
• meeting notes (more on those in a bit), and of course
• technical documentation.

And in writing, your No. 1 priority is clarity.

Not beauty, elegance, or cleverness. Those all have their place, and there is some room for them in professional writing as well, but you should never sacrifice clarity for any of them.

I would also say that being clear is more important than being friendly. If there is something that you need to express, but you can’t do it in a friendly manner if you’re being clear, I’d say you should be clear, rather than friendly. However, not being particularly friendly doesn’t mean being disrespectful — even if you’re expressing strong disagreement, you can do so in a respectful manner.

Clarity takes two forms

Writing clearly can mean one of two things:

• Clarity of expression, that is, caring about how we write each sentence (and word, really) with a view toward maximum clarity.

• Clarity of structure, that is, caring about how we design “documents” (in the broadest sense), so that they are clear and easy to understand, and are useful for communication.

Both of them are equally important, and they depend on each other: a beautifully structured document is useless if it’s full of gibberish, and splendidly clear words are useless if they end up in an unstructured wall of text.

So we’ll spend some time on both, starting with clarity of expression.

---

Orwell’s Six Rules

One of the simplest, most concise, and most useful rulesets for writing clearly in the English language comes from George Orwell‘s 1946 essay, Politics and the English Language.

In it, Orwell suggested six rules for writers to follow:

Rule 1

Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.

What Orwell means by this is essentially, “don’t try to be clever”. If you’re using a metaphor, chances are that it’s not original, that somebody else has used it before, and that people may see it as a tedious trope.

More importantly though, your reader might simply not be familiar with the metaphor, depending on their background. As an example, if your readers are from Germany, or are medieval scholars from somewhere in Western Europe, they will probably understand what you mean by calling a salesperson a Pied Piper. If they are not, your readers will be very confused by your reference to a 13th century rat exterminator (or musician, depending on viewpoint) in your writing.

Rule 2

Never use a long word where a short one will do.

It’s remarkable how much clearer your writing gets if you ruthlessly edit it. English almost always gives you a choice between using a long word, and a shorter one with the same meaning. Always opt for the short one. Rather than utilise, write use. Rather than saying methodology, say method. Instead of I don’t mean to insinuate, you can write I don’t mean to suggest.

Rule 3

If it is possible to cut a word out, always cut it out.

When you’re using shorter words instead of longer ones, you cut syllables and letters from your writing. Naturally, you can also extend that concept to cutting whole words.

There’s a famous quote that fits well with this particular rule that comes from the French writer, poet, and aviator Antoine de Saint-Exupéry (best known to English-speaking readers for his novella The Little Prince).

« Il semble que la perfection soit atteinte non quand il n’y a plus rien à ajouter, mais quand il n’y a plus rien à retrancher. »

(Terre des hommes, 1939)

In English, that roughly translates to:

It appears that perfection is achieved not when there is nothing left to add, but when there is nothing left to take away.

(I say roughly because cut away would be a better translation than take away, but in English the former sounds unnecessarily harsh.)

It needs to be said that this quote disagrees with itself a bit, because it does contain a phrase that is perfectly okay to edit out. If he followed his own advice (and was a little more assertive), Saint-Exupéry could have written:

Perfection is achieved not when there is nothing left to add, but when there is nothing left to take away.

But it is a good quote to go by, still. If you make it part of your mindset to send an email, or hit the Save button on an issue comment not when you can’t think of anything to add, but when you’ve tried to trim all the fat and find nothing else to trim, that will make you a better professional communicator.

Rule 4

Never use the passive where you can use the active.

Orwell’s rule No. 4 states that you should be using the active voice whenever you can. There are some exceptions to this, but in general the active voice tends to be shorter, more concise, and thus clearer than the passive voice.

• Passive voice: The system was rebooted.

• Active voice: We rebooted the system.

Sometimes, it’s difficult for non-native speakers to even recognize that they are using the passive voice. There’s a neat little trick to apply here: if you can take the sentence and append “by dragons” to it, then it’s passive voice.

Applying this rule, we could edit the Saint-Exupéry quote even more radically:

We achieve perfection not when we can’t add anything, but when we can’t take anything away.

Now of course, the quote becomes less and less poetic as we edit it. I’m not trying to say that Saint-Exupéry ought to be writing any differently than he did. What I’m trying to say is that the last version is probably the clearest to most people (including those for whom English is their second or third language), and that in professional communications we shouldn’t strive to be poetic, we should strive to be clear.

Rule 5

Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.

Orwell’s fifth rule emphasises simplicity and accessibility. If there is an uncommon word that means the same thing as a common one, always use the common one.

Note that this means that you can — and should — use technical terms if they have no everyday equivalent. That’s simply because using an imprecise term would mean losing clarity, when compared to using a precise term. But when we have one that we can easily replace with a common word, we should do so.

For example:

1. This is a favourable conceptualization.
2. This is a good idea.

Here, we can simply replace the uncommon terms with common ones.

Another example in the corporate world is that we can easily replace the jargon term “human resources” with “people”, and also replace “acquire” with “hire” or “buy”, depending on context.

1. For this project we’ll need to acquire more human resources.
2. For this project we’ll need to hire more people.

Rule 6

Break any of these rules sooner than say anything outright barbarous.

And finally, Orwell reminds us that while this ruleset is a good guideline to follow, it is not absolute.

Yes, sometimes the passive voice is just fine, such as when you want to make a point of not assigning blame for something that went wrong, to a particular individual or group. Sometimes you can include a witty quote unedited, even though it used jargon or a foreign word.

But having the rulebook in the back of your mind at all times is guaranteed to improve your writing.

Little things

Let’s look at a few other, small things that you can think about to make your writing better.

Parallelism

Parallelism (parallel structure) is the simple rule that if you are using a particular structure in a sentence, then you keep using that structure until the end of the sentence.

1. We wanted to know the time, the place, and where we were going.

2. We wanted to know the time, the place, and the destination.

In this example, both sentences are correct English, even though the first one may sound a little colloquial.

The second sentence is clearer, because the use of “we wanted to know the time, the place, and” primes the reader to expect another instance of the definite article “the”, followed by a noun. Finishing the sentence by “the destination” makes for a more straightforward reading experience.

Emphasis goes last

Most English speakers subconsciously read the end of a sentence as being more important than its beginning. Thus, whatever you consider the more important aspect should go at the end of the sentence for emphasis.

1. The drug is highly effective, but has significant side effects.

2. The drug has significant side effects, but is highly effective.

The first example emphasises the side effects. Thus, most readers would read it as a warning to prescribe the drug with caution. The second example emphasises the drug’s effectiveness, and could thus be seen as an encouragement to prescribe the drug for treatments.

Effectively using bullets in a sentence

In professional writing, you often have the opportunity to make a long sentence much more readable, by simply injecting bullets.

Take this example:

It is important that we listen to the customer’s needs, build a good solution that keeps us within the applicable regulatory framework, and clearly delineate responsibilities in the proposal and SLA.

This sentence is perfectly correct, and it isn’t even awkwardly structured. It is just a long, run-on sentence, which most readers will find difficult to grasp at a glance. You probably reread it once or twice.

Compare this version:

It is important that we

• listen to the customer’s needs,
• build a good solution that keeps us within the applicable regulatory framework, and
• clearly delineate responsibilities in the proposal and SLA.

In this version, not a single word has changed. The statement could still use further editing. But even at this stage, most people will find reading this version much easier than reading the original. That is because most readers will be able to grasp the initial part of the sentence, “it is important that we”, at a single glance, and will also be able to notice at a glance that there are three bullets.

That is to say that without even reading it in full, your reader will understand that you are about to mention what’s important, and that there are three things you suggest to consider.

Writing positively

Writing positively means to write using affirmations, rather than negations. In other words, you state what is, rather than stating what is not.

1. The project manager may not hire outside contractors except those that have been carefully vetted for reliability.

2. The project manager must vet all outside contractors for reliability.

Here, we have transformed the negative structure “may not… except” into an affirmative one, and we’ve further cleaned up the writing by eliminating an example of passive voice (“carefully vetted [by dragons] for reliability”) and replacing it with active voice.

Punctuation

… does matter. Really.

People often overlook how important punctuation is to clarity. What follows is an example of changing the meaning of a sentence drastically, by inserting commas.

First, we are dealing with a perfectly normal panda:

The panda eats bamboo shoots and leaves.

With one comma, the panda becomes a picky eater who takes off after eating the bamboo shoots, rather than also eating the bamboo leaves:

The panda eats bamboo shoots, and leaves.

And with two commas, we’re suddenly dealing with a panda that’s a gun nut with an anger management problem:

The panda eats bamboo, shoots, and leaves.

Whitespace

Whitespace normally goes after punctuation, not before.

In English (in contrast to some other languages), when whitespace precedes punctuation, it’s almost always wrong. The correct sequence at the end of a sentence is full-stop (or exclamation mark, or question mark) followed by whitespace. Likewise, it’s first comma, then whitespace. First semicolon, then whitespace.

There are select exceptions to this rule: whitespace does precede the en dash (–), opening quotation marks, parentheses, brackets, and braces, and optionally the em dash (—). But whitespace preceding punctuation at the end of a sentence is always an error.¹

Question marks (?)

Questions should end in a question mark, shouldn’t they?

Don’t end questions with a full-stop or an exclamation point in professional writing. That will likely come across as either passive-aggressive or confrontational. End questions, even rhetorical ones, with a question mark.

Exclamation marks (!)

Use no more than one explanation mark per paragraph. Zero is fine, too.

Exclamation marks are something you want to use sparingly. Never use more than one in immediate succession. Limiting yourself to one per paragraph is a good rule of thumb.

Semicolons

1. Semicolons are great; splitting the sentence in two is usually better.

2. Semicolons are great. Splitting the sentence in two is usually better.

English mandates that on either side of a semicolon, you have what constitutes essentially a full sentence with a subject and verb (both obligatory) and an object (optional). Thus, they give you the option of just splitting the sentence into two — that is to say, replacing the semicolon with a full-stop.

Possessive apostrophe

• Oscars: more than one Oscar
• Oscar’s: of or related to Oscar

A common mistake that native speakers of German or Swedish often make is the omission of the possessive apostrophe. English doesn’t have much in the way of cases, but does have something like a genitive case. If something is of Oscar, or related to Oscar, it is Oscar’s — such as Oscar’s car, Oscar’s job, Oscar’s house. An “Oscars job” is a job for multiple people named Oscar, or a job at the Academy Awards.

It’s vs. its

Infuriatingly, the possessive apostrophe does not apply when the thing that something is related to is simply it. It would be perfectly reasonable to assume that when we refer to the car in “the car’s roof” as it, it becomes “it’s roof”, but alas, things don’t work that way.

• it’s stands for “it is” (or “it has”)

• its means “of it”

Yes, this is illogical and immensely confusing. English is weird.

Parentheses and brackets

Parentheses (like these) are always removable, without taking anything (of significant value) away from the statement.

You can use square brackets to shorten quotes.

To be, or not to be. That is the question. […] To die, to sleep. No more!

Angle brackets often serve as placeholders, for when the reader must replace <important thing> with <other thing>.

Hyphens and dashes

Often, people think of the three principal forms of dashes as being interchangeable. They really are not.

• A hyphen, sometimes just called a dash, joins word-pairs together.

• En dashes, that is dashes roughly the width of a lowercase n, identify things like ranges or dates (March – June, page 47–49).

• Em dashes — like these, which have the width of a lowercase m — can replace parentheses.

Avoiding Germglish (and Poglish, and Ukrainglish, etc.)

As with accents, I personally think that we should celebrate the little language quirks that come from influences of our native language on English as a second (or third) language. Unfortunately, not everyone is so tolerant, and sometimes English monolinguals are particularly pesky about these things.

So, what follows are a few little things to think about when it comes to typical crossovers from our respective native languages, to English.

…, or?

Adding the suffix “…, or?” to a statement that you want to follow up with a question that asks for confirmation is very common in German and Swedish. But it is a structure that does not exist in English.

You must instead use an interrogative phrase, such as:

• This is a good idea, right?
• That is an excellent proposal, isn’t it?
• I thought we agree on that, don’t we?

“Disturbance”

Swedish and German native speakers often mentally translate the nouns “störning” or “Störung” into English as “disturbance”. This is a natural error because these derive from the verbs “störa” and “stören”, respectively, for which the English translation is indeed “disturb”.

However, in English “disturbance” is usually read as shorthand for “civil disturbance”, or “disturbance of the peace”, which are euphemisms for a violent riot.

Thus, to an English speaking recipient the statement “we have a disturbance in our data center” would sound much more dramatic than the native German sender probably intended it to be.

Articles

Many Eastern European languages (such as Polish and Ukrainian) don’t use articles, and their native speakers frequently omit them when speaking English. In standard English however, the and a are not optional.

Applicable exceptions are newspaper headlines (“Congress passes law on guns”) and controlled vocabularies (such as troops in combat using voice procedure, “gunner, sabot, tank, on my command, fire”).

But in regular spoken and written communications, English speakers use both definite and indefinite articles.

Subject

English sentences always mention the subject.

English, unlike Spanish and many Slavic languages, is not a null subject language. With very few exceptions, you can never leave out the subject in a sentence — even when it would otherwise be clear from context.

For example, in the English sentence “I am hungry” the “I” is redundant, because the form “am” uniquely identifies the verb as being first-person singular. Still, the sentence cannot be shortened to “am hungry,” because that would simply make it incorrect.

Lowercase “you”

Unlike in German and Polish, English speakers never capitalize you in the middle of a sentence, even when using a polite form of address. “Thank You for Your help” would look odd and antiquated to them.

Now, let’s move on to clarity of structure.

---

Five paragraphs that matter

Sometimes there are pretty complex things that you want to convey to a group of people. This is a where lot of people would be inclined to call a meeting — but in reality, there’s a much better way to do that, in writing. And doing it in writing will help you do it in a much clearer, more concise, and more efficient fashion.

Whenever you need to thoroughly brief a group of people on an important matter, in writing, consider using a 5-paragraph format.

What follows is a format that is being used by many armed forces; in NATO parlance it’s called the 5-paragraph field order.

1. Situation
2. Mission
3. Execution
4. Logistics
5. Command and Signal

Now I’m generally not a fan of applying military thinking to civilian life, but in this case it’s actually something that can very much be applied to professional communications, with some rather minor modifications:

1. Situation
2. Objective
3. Plan
4. Logistics
5. Communications

Let’s break these down in a little detail:

1. Situation is about what position we’re in, and why we set out to do what we want to do. You can break this down into three sub-points, like the customer’s situation, the situation of your own company, any extra help that is available, and the current market.
2. Objective is what we want to achieve.
3. Plan is how we want to achieve it.
4. Logistics is about what budget and resources are available, and how they are used.
5. Communications is about how you’ll be coordinating among yourselves and with others in order to achieve your goal.

What if that’s too formal?

Sometimes these headings may look overly formal. People who are not used to that format might actually find it off-putting. You can totally use more colloquial headings, to make your communication less formal. For example:

• Why am I contacting you?

• What do we want to achieve?

• How are we going to do that?

• What will we need?

• How will we communicate?

You’ll quickly notice that these map precisely to the concepts of situation, objective, plan, logistics, and communications. But they sound much more casual and informal and approachable.

Updates

Sometimes you need to convey updates to your plan. Then, it’s often not necessary to redo the whole 5 paragraphs. Instead, you just leave out the bits that are unchanged, compared to your previous plan.

However, it’s always a good idea to include the following 3 paragraphs:

1. Current Situation
2. Current Objective
3. Updated Plan

And the reason for this is easy to explain. There are really only two reasons why you would update your plan: either because the situation is different (the circumstances have changed), or the objective has been modified. And people should know which of the two it is.

Meeting notes

It’s a very common misconception for people to think that meeting notes are for the people that were in the meeting, so they can remember what was said.

News flash: if you have people in the meeting that can’t remember what was said, maybe they didn’t actually participate and shouldn’t have been there in the first place?

So, who do we write meeting notes for? For the people that weren’t in the meeting.

Every meeting needs notes and a summary, and you need to circulate these notes not only with everyone who attended the meeting, but with everyone who has a need-to-know.

And the way you write them is so a person wo wasn’t there, or may not have known of the meeting, or perhaps even wasn’t part of the organization at the time of the meeting, can understand what was said, what was discussed, and what was decided.

There is one person that I can guarantee is never in a meeting you are attending today, and that is you, but six months from now. Looking back at the notes of a meeting that you participated in, six months after the fact, is a terrible experience if the meeting notes are not good. Writing good meeting notes today means making your life, six months from now, easier.

It follows logically, from the requirement that people who were never in the meeting must be able to read the meeting notes and understand everything that they need to know about the meeting, that only the written word counts. What’s not on the written record in a meeting did not happen.

Who’s responsible for meeting notes? The meeting chair (the person that called the meeting).

Who pulls the meeting notes together? The scribe (the appointed note-taker).

Who writes the meeting notes? Everyone.

Meeting notes structure

In terms of what you want to include in your meeting notes, here’s a reasonably useful structure.

1. Meeting title
2. Date, time, attendees
3. Summary
4. Discussion points (tabular)
5. Action items

Section 4 would be the longest, and should indeed list everything that was discussed in the meeting. It is usually practical to organise the individual points of discussion in a table. If you keep your action items in issue tracker references, you may also include those in the table together with the corresponding items you discussed. At that point, there is no need for a separate section 5.

And now… the No.1 Awesome Writing Superpower

Here it comes, the No.1 superpower that will improve all your writing, every time. Are you ready?

Read things out loud.

For real. I am dead serious about this one. It’s pretty safe to say that nothing will improve your writing as much as getting into the habit of reading things out loud as you edit.

There are a number of reasons for this:

• You can read silently at about 250 words per minute, but you can speak at only about 150. Reading things out loud deliberately slows down your reading, and gives you a better chance to spot your own errors.

• Forcing yourself to recite what you wrote will make it easy to detect run-on sentences, confusing phrases, and errors in flow. You will naturally want to correct these, and it will make your writing better.

• Making time to read what you write simply means your mind will stay on topic longer than when you just bash something out and immediately send or publish it. This additional time gives you the opportunity to spot more mistakes, detect errors in your thinking, and have better ideas.

Do not squander all those opportunities. Read things out loud.

Guess what I did with this article.