Write Like A Programmer

I program computers and I also write. There is more than one way to program, but there are a few good practices in programming which have analogous good practices in writing. Here is how you write like a programmer.

The following is not necessarily advice.

First, write with purpose. Do not write just because. Don't write because you love writing, because you love reading your own writing, because you love other people reading your writing or because you love feedback. Instead, write because you have an objective. Your text is supposed to achieve something. Write because you want your writing to accomplish something, because you want your writing to have an effect on the reader.

In fact, flip those two things around in the phrase, in order to make the emphasis clearer: First, develop an objective. Discover that there is a story you want to tell, a particular piece of information you need to share, an emotional instant that you want others to experience, a particular reference work missing from the world. Second, in order to accomplish that objective, write.

Write a first draft. Get it out in front of you, in a basic form. Then start thinking. What are you trying to achieve? How does the thing in front of you achieve this, or doesn't it? How does it need to be modified to better achieve this goal? It's easier to edit from a thing to a better thing than it is to build on blank space, a winking cursor in an empty text editor.

Planning is fine in principle. It can save you time in the long run, if the thing you're writing is large. But you cannot work everything out before you start. It is possible to spend your entire life hypothesising about what words you will use when you eventually write the thing, and never write the thing. A time comes when you must get your hands dirty, and physically touch a keyboard. Once you start writing for real, you may discover important facts which mean all your planning was pointless. This is undesirable, but also unavoidable. The only solution is to get started.

Then, edit. Refactor your text. Just because you've reached the end doesn't mean you're done. The first thing that it occurred to you to write was almost certainly not the best thing to write. Re-read the text, and be critical. Put yourself in the mindset of a critic, actively searching for faults or weakness. Stay focused on your objective, and remember that every line of your text must serve this objective. Keeping this purpose in mind makes it easier to be dispassionate and pragmatic.

Be organised. Divide your major objective into smaller ones and use chapters or section breaks to address these individually. You can go to an extra level of granularity with individual paragraphs. Group statements into paragraphs according to purpose and subject matter. Make them self-contained. Try not to refer to topics or terms before they have been adequately introduced.

State exactly what you mean, and try to avoid ambiguity or misunderstanding. Don't ramble. Don't let sentences get too long. Don't try to convey too many different thoughts in a single sentence. Break things down into simple terms. "Simple" does not necessarily mean "obvious". Simple terms can take quite a bit of thought to come up with. Sometimes it can be obvious that there is a simple term, but not obvious what it is. Avoid idioms.

In general, choose your words carefully. Word choice error is normal and unavoidable. A word which made perfect sense at the time you wrote it can be obviously wrong once you come back to it later, with the entire rest of the document clearly in your mind.

And be brief. In fact, be merciless. Murder your darlings once they cease to be useful. Yes, that paragraph is beautiful, you slaved away on it - but it no longer serves a needed purpose, so scrap it. It's okay: there are limitless more words in you, where those came from. You are not a dumber person now that you've written them, or now that you've deleted them; you are capable of equally excellent paragraphs, still.

Remove unnecessary words and statements. However, do not misunderstand the meaning of the word "unnecessary" here. An unnecessary word is one which does not serve your objective. However, just because a word or statement can be removed, and left implicit, doesn't mean it should be. Clarity can serve your objective. Brevity is good, but clarity is better. Brevity is good for keeping a reader's attention, delivering a good density of information and/or action. It means the reader's time is not being wasted. However, too much brevity becomes obfuscation. Without clarity, a reader reaches a point where they just can't keep reading at all because they can't understand what you're saying. Sometimes, repeating yourself for clarity is appropriate.

With clarity in mind: Punctuate correctly, capitalise correctly, format consistently, and check your spelling. Minor errors of this nature are not fatal, but they slow the reader down. They can mount up and become irritating, making your text genuinely unpleasant to read, or even unreadable.

Check your facts and be sure of them. Clearly separate your own opinions from factual statements.

Do not work in a vacuum. Read other people's work. Look for good writing, and don't just passively experience that writing, focus hard on it so you can see what makes it effective. Take notes. Have other people read your work, and if possible cajole them into giving you notes in turn. Make sure that you are not the best writer you know.

And for the love of God, use libraries!