Another very early article, from 2006, but very much in the spirit of the explaining series. – Russ

Some years ago I was managing a software group that was doing joint development with a team in Japan. My company spent a lot of money to translate a design document from Japanese into English. The result was indecipherable gobbledygook. When I complained about the quality of the translation to the Japanese manager, he just shook his head. No, he said, it wasn't the translator: the document was just as unreadable in the native Japanese. And nobody was surprised.

For a profession full of sharp people, software engineering produces some hideous prose. How many times have you tried to read a technical document and failed because it was, in a very real sense, unreadable? It doesn't have to be this way. We technical types can improve our writing simply by applying some of those hard won coding skills to to those other, human, languages. I may be grammar challenged and spelling incapable, but writing code has taught me a few things about writing for people.

Do one thing well

If we have learned anything about building programs in the last few decades, it is that each method, class, module or program should do one thing, and do it well. When a GUI tries to be both pretty and the center of the business logic, you are headed for disaster. Write database code that also tries to handle the network traffic and you are just setting yourself up for a fall. No, a program needs to concentrate on one thing, and do the best it can at that one thing.

So does your writing. If you are writing installation instructions, tell me how to install the thing. I don't want the theory of how it works. I don't want to know how it was was designed. I don't want to know why you picked Linux over Mac. I just want to know how to install it. I don't think that people deliberately wander off the point, but a lot of technical people are just dying to tell the world what a great job they have done, why they picked this over that, how hard it all was. Great: write a status report, or a blog, or the Great American Technical Memoir. The practice will do you good. But as for the installation instructions, just tell me how to install it. Then write the best code…er…English that you can come up with to make that happen.

Test, test and then test again

The oldest joke in software engineering is probably the one where the engineer says, Well it compiles, so it must be right. Everyone in the software business knows that getting a program to compile is just the first, and usually the easiest step to getting it to work. If you want to know if some code works, you need to run it. If you want to know if your prose works, read it. Out loud. There is something about running your words out of your mouth and back into you ears that is the text equivalent of unit testing. If you find you are gasping for breath, perhaps your sentences are too long. If reading your stuff makes you feel like you are trying to say She sells sea shells at the sea shore, maybe you should consider rewording. Reading your stuff out loud will also help you spot those places where you annoyingly use the same annoying word in annoying profusion.

I guess that if reading your own work out loud is unit testing, then having someone else read it is beta testing. If part of your job is writing, then a kind but honest reviewer is worth more than a fancy word processor and two dictionaries. And what's the best way to get someone to review your stuff? By reviewing theirs, of course.

Don't repeat yourself (much)

DRY is about as close to a commandment as we have in the programming world. Keeping redundant code to a minimum means that your code is easier to understand, it means that bugs can be found and fixed once, and it means that you simply have less code to deal with. Generally it is much the same when you are writing for people. You want to avoid repeating large blocks of text or the same explanations over and over. If you are writing the design document, don't repeat the requirements; point the reader back to requirements document. Avoid redundancy in your prose for exactly the same reasons you avoid it in code: your document will not only be smaller, but it will seem more organized. If you make a mistake, there is only one place to fix.

Don't take this advice too far, however. People are, well, human, and they do tend to forget. It is not bad to remind your reader every now and then of the some critical fact: remember, as we explained in chapter one, don't let the blue wire touch the detonator. Sometimes you can spot the places where a little repetition will do some good by taking a break and rereading your document later. Things that seemed obvious when you were writing will sometimes become completely obscure an hour later.

Keep in mind that there is no harm in providing some context, but you have to strike a balance between helpful reminders and the deadly retelling of section 1.4.7.c, subparagraph 4.

Don't write to impress me

There are lots of ways to write programs, some good and some bad, but perhaps the worst way is to write code to impress the reader. You see this in programs that refuse to do a simple thing simply. Need to find an particular item in a list of ten? Well let's pull out that highly optimized binary search algorithm. Need to build one dialog? Let's write a special GUI framework to support it. Want to add two plus two? Then clearly you will need a factory which produces the command which grabs the facade for the bridge to your NumberAddition class. I think we have all seen too much code that is written mainly to demonstrate the cleverness of the author.

So why is it that engineers who would never think of coding to impress, write documents that are full of impressive sounding words? We don't have a thing, we have an Artifact. We don't pull it all together, we Create an Aggregation. We don't work together, we Collaborate. And come up with Canonical answers. And don't forget the worst offender, facilitate. Even worse, we string them together: Hey kids, let's aggregate the artifactS to facilitate canonical collaborations!

Don't get me wrong – these are all perfectly good words. The problem with these words, and all of their polysyllabic friends, is that they are like the complex algorithm or the fancy framework. Frameworks and fancy words have their place, but if you are only pulling them out to impress me, it ain't gonna work. Overuse the fancy words and you make yourself sound like you are dumb and trying to pretend that you are smart.

Here's a little secret: getting your point across in as few, short words as possible shows that you care about the reader. It shows that you know your goal is to communicate. It shows that you are just trying to get it done. In short, it shows that you are smart. I can't really do better than to repeat George Orwell, who, seventy years ago, asked if you would rather read this:

Objective considerations of contemporary phenomena compel the conclusion that success or failure in competitive activities exhibits no tendency to be commensurate with innate capacity, but that a considerable element of the unpredictable must invariably be taken into account.

Or this:

I returned and saw under the sun, that the race is not to the swift, nor the battle to the strong, neither yet bread to the wise, nor yet riches to men of understanding, nor yet favour to men of skill; but time and chance happeneth to them all.

So how do you do it? How to you stick to small, pointy words that work? Start by trying to write like you talk. Very few people walk around saying things like Objective considerations of contemporary phenomena… If you say it out loud, most of the pretentious words will simply fall away. Remember, the race may not always go to the swift, but the readers' thanks will always go to the concise.

Wrapping Up

So there it is: know why you are writing and try to get it done. Read it out loud early and often. Don't repeat yourself unless it really helps the cause. And don't try to impress me. If you think about it, writing is the art of programming that wet computer that sits between your reader's ears. When you start, ask yourself how you are trying to change the state of your reader's mind. With that goal firmly in sight, write the best code you can.

– Russ