Writing Tips for Programmers
From a Better Programming copy editor
I’ve been copy editing for Better Programming almost since the publication began. I’m happy to say that, in my experience, programmers are pretty decent writers!
Of course, as copy editors we make plenty of edits — I feel like I’m not doing my job if I can’t find several dozen ways to improve a piece. But even when there are lots of grammatical errors to find, writing structure and organization tends to be very good. Clearly, knowledge of computer languages gives one a logical, structured approach to writing English.
Having said that, there are some areas where I see programmers getting tangled up time and again.
Who Are You to the Reader?
A case study, a tutorial, an opinion piece, a report: each of these requires the author to differently position themselves in relation to the reader; as a lecturer, a guide, a friend, or a journalist, for instance.
Take a look at these four sentences:
- “Next, we’ll take a look at multi-node Kubernetes clusters”
- “Next, you’ll look at multi-node Kubernetes clusters”
- “Now, I’ll take a look at multi-node Kubernetes clusters”
- “Now, take a look at multi-node Kubernetes clusters”
On their own, none of these sentences are wrong, but they each raise different expectations of what’s to come.
“Next, we’ll take a look at multi-node Kubernetes clusters”
The first person plural “we” here sets up the writer as a guide or tutor, leading the reader through a process. This is a popular approach for tutorials and guides.
I’ve noticed that some writers walk the reader through a process and use “we,” and then they use the possessive “our” for absolutely everything — “Next we open up our dashboard …then we click on our submit button …now we’ve come to the end of our project.” Maybe in programming ownership has to be expressed every single time you mention a thing, but it doesn’t in English! Feel free to revert to the default conjunction “the” even after using “we” or “let’s” in a section.
“Next, you’ll look at multi-node Kubernetes clusters”
This uses the second person singular future tense. Because in this sentence the writer isn’t personified (“we” includes the writer and the reader, but “you” only includes the reader), this sounds more impersonal. It’s a straightforward factual statement of what the reader should expect in the piece.
“Now, I’ll take a look at multi-node Kubernetes clusters”
This uses the first person singular future tense. This leaves out the reader and only personifies the writer. It’s the writer’s story — the reader is a passive recipient. This tone is unsuitable for a tutorial or guide, where you want to give the reader a sense of agency and involvement. But it could work well for a review of a new piece of technology, or an account of a conference, to give two examples.
“Now, take a look at these multi-node Kubernetes clusters”
This is the imperative form. You’re telling the reader to actually do something, so this is highly active. This works well for tutorials where you have an expectation that the reader will actually be following along. Of course, it can also be used when you want the reader to examine a diagram or some code within your piece.
The main piece of advice I have here is this: be consistent. Decide at the outset of your piece how you want to be perceived by the reader — as a guide, a lecturer, a funny friend, a storyteller, or an instruction manual. Keep that relationship in mind as you write.
Superfluous Grammatical Redundancy
That headline is an example of grammatical redundancy. Why? Because, by definition, grammatical redundancy is superfluous. That’s what grammatical redundancy means — using more words than you need to.
You could call it being linguistically extra (but in a bad way, because that sounds awesome).
Redundancies are common in spoken and written English. They’re also a concept in programming. Here’s Wikipedia’s definition of redundant code:
“In computer programming, redundant code is source code or compiled code in a computer program that is unnecessary, such as:
recomputing a value that has previously been calculated and is still available,
code that is never executed (known as unreachable code),
code which is executed but has no external effect (e.g., does not change the output produced by a program; known as dead code).”
If we think of the English language as a code for humans (because that’s what it is) then its output is understanding in the recipient. Redundancies increase the amount of writing without adding anything to the reader’s understanding.
Just like a computer language, if a line or expression can be deleted and the output remains unchanged, then that line is unnecessary and should probably be removed.
Some examples of redundancies
“Similarly, their interactive visualizations also come with simple explanations.” Either “similarly” or “also” can be deleted. Both words perform the same function in the sentence: drawing a comparison with something previously written.
“Many times.” Try “often.”
“A large number of…” Try “many.”
“In order to.” You can usually just use “to.”
“Utilize.” This means “use.” It doesn’t make you sound clever, and it wastes two syllables! (This isn’t really a redundancy, just a personal bugbear. Look, just don’t use “utilize,” please.)
I’m not saying the occasional redundancy is the end of the world. I don’t go crazy if someone says “a moment in time” ( all moments are “in time!!!”)
But using lots of redundancies makes writing unnecessarily wordy, long-winded, and tiresome to read, and this reduces understanding.
Just as with good code, good prose is efficient and concise.
As a copy editor and non-programmer, how you format code itself is none of my business (please, argue among yourselves on that subject). But how code is incorporated into the body of your piece on Better Programming, in terms of formatting and wording, is my business. And I have a couple of tips to share.
Better Programming has a simple style guide for all code incorporated into a sentence. Sandwich your code between two of these ticks: ` (that’s the key beneath the Esc key on most keyboards), and your code will appear
If instead, you write your code another way— like this, or like this, for instance — we will fix it. However, whatever you do, please at least be consistent. This reduces the likelihood of mistakes.
If the formatting is inconsistent, we can’t always tell the difference between a function and the word that the function is named after. Or, to put it another way, there’s a difference between Swift (the technology),
.swift (the suffix), and swift (the bird/adjective meaning ‘quick’).
Long code chunks
Usually, longer code chunks, more than a couple of lines, should be in a Gist. However, at the moment, Gists are not rendering correctly on Medium. So, please use
this style even for long code chunks. Three ticks at the start of a paragraph, like this: ```, formats the whole paragraph.
One thing to look out for with longer sections of code — please don’t treat them as part of a sentence. In other words, don’t do this:
Now, open up the file and add
to the end…(sentence continues)
Only a single term or short line of code should actually be incorporated into a sentence. Longer pieces of code should be properly introduced, like this:
Now, open up the file and add the following code:
A Final Word
At Better Programming, we take an active approach to content. It’s the ideas that matter most. If we see value in your content — if it covers a need and is original — we’ll put the work in and get the writing to where it needs to be.
Ultimately, however, the better written your piece is when it reaches us, the better it will be when it is published. A good piece can become an excellent piece, and an excellent piece can be honed to near perfection.
Think about your relationship to the reader, search for and eliminate all the flabby, redundant language you can find, double-check that your code is formatted consistently, and then send your masterpiece to us. We can’t wait to read it!