Write Like You Code | Hacker News Reader

Write Like You Code

chrisbehan.ca

151 pointsenigmatic0267 comments

This writing advice -- recycled from newspaper house style guides -- to use only simple and common words in efficient sentences is becoming almost universal, and yet "good writing" doesn't always obey these rules. Sometimes you need a certain obliqueness and sesquipedalianism to convey a certain effect that simple directness can't achieve. To paraphrase Mark Twain, sometimes you need the right word and not its second cousin; even if the right word happens to be polysyllabic and relatively obscure. Why should literary fiction have all the fun?

Oh, and the author misspelt "sesquipedalian".

edit (added): The Urdu humourist Mushtaq Ahmed Yousufi was often accused of using overly difficult words and obscure literary references from Pashto, Sanskritised Hindi, Persian and Arabic in his Urdu writing. He admitted to favouring "mushkil-pasandi" ('a preference for difficulty') and exhorted readers to raise their standards continuously. And IMO with this device he raised the quality of his own writing from what would have been only a series of somewhat funny observations and gag jokes to masterpieces of the genre.

Alternating between single clause sentences and sentences with two clauses, as the author of the article mostly does, is also not an example of good writing. It is perfectly efficient, just not particularly good. The clauses themselves should patter, creating ventricles that, like the heart, comprise contrasting units through which the gist is substantiated. A lot of the reader's cognitive overhead can be offloaded to the interest of a sentence's construction.

This sounds very interesting but I have trouble picturing it.

Could you provide an example of text with this structure/rhythm?

I agree -- that sort of rhythm may be to the point and good for some goals of technical writing, but is pretty sterile. My favourite quote about sentence pacing:

> This sentence has five words. Here are five more words. Five-word sentences are fine. But several together become monotonous. Listen to what is happening. The writing is getting boring. The sound of it drones. It’s like a stuck record. The ear demands some variety. Now listen. I vary the sentence length, and I create music. Music. The writing sings. It has a pleasant rhythm, a lilt, a harmony. I use short sentences. And I use sentences of medium length. And sometimes, when I am certain the reader is rested, I will engage him with a sentence of considerable length, a sentence that burns with energy and builds with all the impetus of a crescendo, the roll of the drums, the crash of the cymbals–sounds that say listen to this, it is important.

(Gary Provost)

I enjoyed reading this very much! Thank you!

And then Google Translate is applied and it all turns to mush or worse.

Good point. Speaking of the art of writing good sentences, I heartily recommend "First You Write a Sentence" by Joe Moran.

I agree with the whole article though, except for the note about using sesquipedalian words. I agree that there are, in fact, creative usages of such words that make making a point achieve a stronger impact, and I enjoy learning a new word or two from whatever I'm reading. Expanding my vocabulary is one of my motivations for reading as a non-native English speaker.

"- to use only simple and common words in efficient sentences is becoming almost universal, and yet "good writing" doesn't always obey these rules."

I would say it depends what you write and to whom.

If your target is "the internet" where most people only speak simple english - you absolutely want to use simple english, if you want to reach more people.

And also in everyday life I made an effort to value clarity and simplicity in speech way over complicated layered sentences that might have made my teachers proud - but would be cause for further missunderstanding with the people around me (my partner has a different first language than me).

And I would say, the whole world is in a state of confusion caused by missunderstanding. If people would speak and write a bit more clean and clearly (like good code) I think everyone would benefit.

That being said, if you want to reach a higher level of communication - and not just pass mere facts, but adress emotions and deep thoughts - than yes, there is the great art of poetry. Natural languages are not mathematical precise for a reason.

But as long as basic simple communication is not working - I think it is seldom helpful to use even more complicated/vague language

>And I would say, the whole world is in a state of confusion caused by missunderstanding. If people would speak and write a bit more clean and clearly (like good code) I think everyone would benefit.

many professions have concepts that are complicated to understand for people outside the profession and as such develop their own jargon.

The development of jargon that is perceived as unfriendly and complicated to people outside the profession is often driven by the need for greater clarity inside the profession.

Finally in the case of programming languages and clarity arguments, clarity relates to your expertise, the less expert phrasing is sometimes overly verbose and destructive to quick comprehension, while the expert phrasing may seem incomprehensible to the non-expert.

"clarity relates to your expertise, the less expert phrasing is sometimes overly verbose and destructive to quick comprehension, while the expert phrasing may seem incomprehensible to the non-expert. "

An expert programmer should write adequate code for the target audience - the people who will actually read and work with that code later. They need to understand it, so he or she should not use advanced constructs, when beginners will work with the codebase.

Likewise with scientific language:

If you speak to fellow scientists you can and must use your special language. Way more efficient.

But if you give a press conference to present your findings, you have to use simpler terms, if you want people to understand you.

Many great discoveries probably got lost that way, because scientific language was not translated adequately.

It's easier to hide bad writing with more difficult words. When writing in a way that's easily understandable, bad writing or arguments that don't make sense become much more evident.

I see it as a progression. It's easy to lie to yourself and think you're a good writer by clouding your prose with difficult-to-understand sentences.

I think once you've mastered writing simply, you can be confident that you're able to move on to more difficult prose without using it as a crutch to obscure bad writing.

I agree with this. Most people need to simply their writing and convey their ideas more clearly. Once you've mastered that, you can explore more sophisticated prose.

Treat fancy words and constructions in your writing like seasoning on your food.

A bit here and there makes it more interesting. Too much makes it indigestible.

1) We tend to pay more attention to what is more difficult[0], and paying more attention is often how we become better at something.

Successful teachers and instructors don’t “chew” everything out and explain in simplest possible terms but rather facilitate an involved process throughout which the student has to make own effort in order to arrive at an understanding and in the end experience an “aha!” rush that is stronger, more memorable and inspiring.

If I am reading a piece of writing and a word takes a moment for me to understand or I’m redirected to a footnote for no obvious reason, that itself might just make me remember the idea better; if I suddenly notice a second layer of meaning, the feeling of connection with the author facilitates deeper understanding. (And if I stopped reading at that point due to insufficient motivation, perhaps that’s how the author intentionally made me self-select out.)

2) Not every idea can be directly verbalized.

One could argue that whatever can be conveyed in writing by words in their direct literal meanings is only sufficient for communicating strictly technical information. Imparting a non-trivial concept, a feeling or emotion requires lateral, indirect approaches—and that’s where author’s choice of words, idioms, rhythm, connotations, anything can play a role. (Think of background music in a film and how it influences your impression; try watching a piece of dialogue while playing an uplifting/energizing piece of music and notice how the mood changes.)

[0] In non-arbitrary ways; it’s a fine line between keeping readers on their toes and trying to be obscure for the sake of it.

Also Mark Twain: "I never write metropolis for seven cents because I can get the same price for city."

I recently did a short training on technical writing. One piece of advice stuck with me because it is a) counter intuitive and b) not followed widely enough. It can also be said to follow "write like you code", so here it goes:

When writing a technical document, stick to one word per concept. Say you are using "throughput" for how many requests per seconds a service handles in a given period of time. Don't rename it to "load" in the middle of a sentence. People will waste time wondering if it's the same concept or subtly different.

This is the opposite of what we've been taught at school (avoid repetition! use synonyms!), so it takes a bit of discipline to follow it.

> When writing a technical document, stick to one word per concept

Yes, this is absolutely critical. As a tech reviewer I once came across a doc that used no fewer than seven different terms for the same underlying thing. Part of the problem was that it has been written by at least two authors over a couple of months. At least one of the authors admitted that they hadn't take the time to remind themselves what had already been written.

In non-fiction, it can be good to introduce variety, and challenge the reader But as a tech author, if the reader has to work to keep track of things through a doc, simply because you have been lazy to check for consistency, you have failed.

[Edit] There are a couple of things that can help avoid the problem. The most important is to have a final step that involves consistency checking. Where I used to work, we encouraged a peer-review step before docs where submitted for formal tech review. This significantly reduced the workload on the formal reviewers.

Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept. Did you mean tech docs as a subset of non-fiction? English is my second language and I always have to think twice translating fiction (into fantasy) and non-fiction (into real).

> Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept

Good point! I'm guilty of the problem myself. I did mean tech docs as a subset of non-fiction. In these terms, I would now state that technical docs should use 'one term per concept', but that non-fiction doesn't have to as long as some ambiguity is acceptable.

This is not just for technical writing and coding. It goes for communication and thinking in a technical context as well. You're going to make so many design mistakes if you use several words for one concept, or the same word for multiple concepts.

I know the Sapir-Whorf hypothesis is discounted by linguists, but I believe I have loads of first-hand experience showing how word choice affects design decisions in fairly strong ways.

And that shouldn't really be surprising. We're not discussing things we can plop down on the table in front of us. We're discussing abstractions. We're discussing machines of the imagination. The only way we can construct them in each other's minds is by putting words together in the right sequence. Obviously, the choice of words are going to affect how people picture these machines in their heads.

We cannot be careful enough with the language we use when we try to build complex things.

I know it’s not the point of your comment, but the Sapir-Whorf hypothesis is about how your language itself structures your thinking, not word or grammar choice in individual utterances or writings made by an individual.

Aha! I never dug deep enough into the issue to learn that. Thanks!

Is there a name for the phenomenon I'm referring to?

I don't see your correction. Individual word or grammar preferences are to Sapir-Whorf what tactics are to strategy.

Not quite. Sapir-Whorf is specifically about the _structure_ of a language, meaning its syntax, morphology, etc.

Vocabulary choice obviously influences how you interpret a specific utterance, but Sapir-Whorf is about how a language's structure influences its speakers' cognition at a basic level, i.e. _how_ they think, not _what_ they think.

Very good advice. I guess the "side effect" of using the same word everywhere is pointless in a technical context; nobody worries about their technical writings being "boring" or repetitive...

A lot of the stuff we learned at schools turned out to be bullshit or even harmful.

To be honest this one is neither. It just works poorly under very specific conditions.

>When writing a technical document, stick to one word per concept

The problem comes since this doesn't make it seem like you have a wide vocabulary. A large vocabulary is naively indicative of intelligence; why you'll see inexperienced people using flowery complex language in a multitude of different ways to explain the same ideas..... Certainly proliferated from American English. Annoying.

This applies quite generically to coaching as well: if the person you're listening to uses a certain word to describe something, continue to use that word yourself instead of trying to paraphrase it.

In that sense, you're sticking to one word for a concept, but the word is given to you by someone else. And by using their terminology and not your own refactoring, you are making sure that you're not distracting them from their own thinking.

Another thing that annoyed me in tech writing when I was still fresh in the field was when all the examples built upon the previous and then out of nowhere the next example was different. IE: some author has spent a couple chapters building up, I dunno, some coffee shop website but now that they want to discuss concurrency they're going to switch to a CLI app that hits Wx sites for the current weather.

Interesting. I’m guilty of this in my online writing in the name of SEO. After all, my readers might search for either term. This probably makes my writing worse.

Yes! This annoyed me for so long, and I only recently learned that it happens (in part) because non-technical writing strongly encourages so-called “elegant variation”[1]:

https://en.wikipedia.org/wiki/Elegant_variation

Unfortunately, elegant variation spills over into “non-technical” cases were technical precision is still important, and that becomes a problem — like if you’re whether you’re supposed to know that the Pope is the same as the Bishop of Rome.

[1] Great quote from the article about the absurdities that the practice introduces:

>>A humorist imagined writing a news article about Gaston Defferre: "It's OK to say Defferre once, but not twice. So next you say the Mayor of Marseille. Then, the Minister of Planning. Then, the husband of Edmonde. Then, Gaston. Then, Gastounet and then ... · Well, then you stop talking about him because you don't know what to call him next."

> This is the opposite of what we've been taught at school

Not exactly. Schools don't tend to teach this concept, but there is a difference between

• regular "words" — which are only defined descriptively by anthropological observation of usage; whose usage and shades of meaning evolve memetically; which can have different shades of meaning to different people; where people using a word in a novel way can't really be said to be using it "wrong", only "unclearly" — and not even that, if their usage later catches on;

• and jargon terms — which are defined prescriptively in some originating document somewhere; where jargon can be used "correctly" or "incorrectly"; where everybody attempting to "properly" use a given jargon term is trying to convey exactly the same meaning from the originating document's prescriptive definition.

Jargon terms aren't specific to technical writing; they're quite common in everyday prose as well. For example, units of measure are jargon terms. You would never even think to try coming up with a synonym for "degrees Celcius" or "US Dollars" if you wrote it several times. You'd at most abbreviate these, or leave them off of successive entries in a list of same-united things.

The key realization of technical writing is that you yourself can create jargon terms — define them just for the purposes of your document; and that it's extremely helpful to readers' understanding of an opaque subject when you do so, because you're making it clear by doing so that this is (at least in your own presented mental model) a distinct important concept to be lifted out and thought about on its own, a proposed new mental tool in the reader's toolbox for dealing with the problem domain.

Good writing is utilitarian. Boring but it serves the purpose of communication.

Great writing is much more. It communicates and entertains. Here are 2 of my favorites relating to computerz:

https://aphyr.com/posts/341-hexing-the-technical-interview

http://scholar.harvard.edu/files/mickens/files/thenightwatch...

Although I do agree the advice does make sense for most of us, who just aren't very good at writing. But if you do have the skill to write well, do it! I love great writing and love people who aspire to it, even if they fail! Everything you do does not have to be packaged up to maximize mass appeal and resume points.

Thanks so much for acquainting me with "Hexing the technical interview" and "The Night Watch". I don't think I've ever before read great writing by great programmers. Now I have.

I'm glad you liked them! Spread the word :D

The advice should not be a rule of thumb.

Fortunately not every communication has for sole purpose to transmit information efficiently. Most communication indeed are not an elevator pitch nor should be BLUF.

Efficient writing style or communication style in general does not correlate well with an economy of signs. A certain type of communication, targeted to busy people for example, does.

Should I want to extend the article to absurd limits, it could read "do not write poetry nor prose".

Please DO write poetry or prose, we need it. Simply avoid it when your readers do not want or expect it (eg. at work).

I disagree with the premise that writing concisely is analogous to writing concise code. In fact, the opposite is more likely true.

Why do we still have thousands of poorly written program error messages of the meaningless 'invalid value' kind? Everyone immediately recognises this staccato style of writing common among developers.

Even modern programming languages have terrible compiler error messages. (Rust has made a commendable effort to display readable English compiler error messages.)

All this suggests to me that developers who write their English like their code are writing like a computer, not writing for other humans.

---

Here are two recommendations for writing clear English (excludes fiction) :

Plain English Campaign

This is a campaigning organisation from the UK which promotes clear, easy-to-understand written English suitable for any industry or profession.

Here is their clear, simple and short guide on How to write in plain English [PDF]:

http://www.plainenglish.co.uk/files/howto.pdf

---

GOV.UK: 10 tips for clear writing

I find the tips at the following link very helpful:

https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/

You don't need to listen to the podcast at the top of the linked page (unless you want to). Scroll down the page and you'll find a short description of each of the following tips:

1. Establish ‘The Point’

2. Write it like you’d say it

3. Don’t try to sound clever

4. Show the thing

5. Know that you are not your writing

6. Share your work

7. Read (poetry in particular)

8. Never start with a blank page

9. Know when enough is enough

10. Stay human

“Programs are meant to be read by humans and only incidentally for computers to execute.” -- D. Knuth

I believe that the ones who create error messages like "Invalid value" (without telling you the value nor why it was invalid) or "File not found" (without telling you the attempted file path) are not really good programmers.

Concise != stripped from essential information.

And I'm saying that as someone who always valued concise style of writing, and often got an equivalent of D (or sometimes F) in Polish writing assignments for my essays being too short. :D

That quote is not by Knuth, it's from Abelson and Sussman: https://mitpress.mit.edu/sites/default/files/sicp/full-text/...

It's also a problematic quote, because it gives people the impression that they can just ignore that there's an actual computer running their code.

Oh interesting, I stand corrected, thank you!

My physics supervisor used to tell me:

"Write in Fourier space, starting at zero frequency and working your way up."

My favorite writing lecture is this one: https://www.youtube.com/watch?v=aFwVf5a3pZM

The number one piece of advice: your writing can be clear and structured, but if it's not valuable it's useless and people will stop reading. If you want to write well, figure out who your readers are, figure out what they value, and give it to them.

> You don't need React for your landing page.

Stop this. Just stop it. If you're any company worth it's salt with a decent landing page, you're going to need things like internationalization, a contact form, maybe even a light / dark mode if you want to be hipster. How are you going to do form validation? Min / max length of message? Email validation? The list goes on and on... These things become 100x easier with a framework like React.

_Yes_, you can do this all with vanilla JS and HTML. But eventually you're going to make a mess. You don't have to use React either - many choice frameworks can help you with all these things.

My quick two cents about programming and writing is that to be great in either (and not just good), it's far more complicated than just a simple set of rules.

For a landing page with one form you don't need React and I question how beneficial it is. You wont need or even use most of the features in React for a landing page. Same for most marketing sites, how much JS do they really need?

For app front ends I might buy the "Just use React" argument, but that still adds significant complexity, especially for a smaller 2-3 person team trying to get an MVP out the door. I don't think it follows that using a more basic framework like jQuery means you are suddenly accruing technical debt. It really depends on your UX needs greatly.

> you're going to need things like internationalization

Links to different urls

> a contact form,

Standard html form

> maybe even a light / dark mode if you want to be hipster.

A flip of a single CSS variable.

> How are you going to do form validation? Min / max length of message? Email validation?

`<input type="email" />`; `<textarea minlength="100" maxlength="500"></textarea>`

> Novice writers use big words to hide their own lack of understanding, similar to how novice programmers use frameworks.

Maybe another good writing rule is that if you have to cut other people down to get your point across, you might not be as good of a writer as you think.

I see the irony of your comment.

It's the other way round. Good code is like good writing, because code _is_ writing: its primary purpose is to convey ideas. To computers, but more importantly, to other humans as well.

The linked Reddit post is kinda amazing:

"Drunk Post: Things I've learned as a Sr Engineer": https://www.reddit.com/r/ExperiencedDevs/comments/nmodyl/dru...

To me Orwell's guide to writing seems to be the best mix of practical and style: https://infusion.media/blog/george-orwells-six-rules-for-wri...

Short, concise and to the point.

The missing 7th rule is "empathise with your target audience". the reason its missed from Orwell's rules I suppose is because he assumed that you were trying to change people's minds, so you would construct your argument from their point of view.

Technical writing should be an exercise is empathy: "how does this thing work, why should you use it, and what areas you might struggle with when trying"

If you write like you code, that will work well for technical specifications where you want to give each requirement exactly in one place, to keep the page count down.

Those documents are a pain for most people to read, though.

People need some redundancy and repetition. When they have some question, they want to find the answer in in one place, not piece it together by deduction from three distant sentences.

Also, write what? You wouldn't write a novel necessarily like documentation. In your novel's plot, if a character dies, you don't have to repeat that fact three times. Novels aren't intended to work that way. If they did, there would be an Index at the back, where you look for "death" under "d", and then there will be an "... of Jack Grape, 234" under that, and there you go: page 234 is where Jack Grape dies.

Or, conversely, people reading your programming language specification do not avoid reading the later sections first, for fear of spoiling the plot! "Wow, this declaration syntax is so exciting, it really has me on edge as to whether there is an object system ... but I'm afraid of reading ahead to spoil the surprise!"

Something written to be read from cover to cover in a linear way as a work of art requires a different approach from a reference work.

Long functions don't necessarily make for bad code. If there aren't long loops or long conditionals, long functions can reveal a lot of structure without the cognitive overhead of many single-use functions.

Good code uses abstraction judiciously. The same in prose leads to parentheticals and rabbit-holes. Good code is both easy to read and easy to modify, but making it easy to modify without losing much legibility is the hard bit. It requires a prediction of the future: what's likely to change and what isn't, and whether future change needs an indirection or if it should be integrated in place. There isn't a close analogue in writing, since writing is a linear tour of a whole, while code reading is usually a breadth-first directed search for the right place to either locate a bug or add a feature.

Great writing uses fresh, vivid and appropriate analogies. Making up new stuff in code is more often than not the wrong thing to do.

The writing which is closest to code is newspaper reporting: starting out with a summary, and iteratively delving deeper into details. This is writing designed to be skimmed by the reader and aborted when the desired information is acquired. The other prose which comes close is documentation. Neither make for great writing.

Agreed with all points. I only read into the first few paragraphs and immediately found it to be overly simplifying the processes of both writing and programming. Good advice for beginners perhaps, but definitely not rules to live by.

Writing unlike coding can use repetition in ways that are valuable to the reader where they wouldn't be valuable to the program (DRY principles).

The concept about delivering value in a given span of time for writing is great and in coding it could be similar to having valuable pieces of code in each function (single responsibility).

Personally I don't understand why I would write like I code. It's more limiting. Wouldn't it be more about coding like I write? There are many lessons in the writing process that already apply to authoring code.

Mind Maps/Whiteboard Ideas -> Outlines -> First draft -> Self Edit -> Professional Edit -> Publication

Each of these steps is similar to a high-level design which can have the biggest optimizations.

I think Steve McConnell & Bob Martin have great weaving of the "code like you write" ideas especially around code readability, self-documenting, reading old code to influence new code, and removing redundancies where possible to name a few.

Write like an automaton, for an audience entirely composed of automatons.

Even technical writing needs to have some sort of soul. Even most technical readers aren't actually game to sit down and read the Intel x86 assembly language reference cover-to-cover.

I write most of my blog posts using Sublime text directly into html code.

There's no spellchecker, it's annoying wrapping paragraphs in <p> tags, but my quality of writing is 10x better.

Something about my weird coder brain is way more comfortable doing my writing as code. I can also tell when a piece of writing is good, because the code looks "nice", the same as if you write a nice elegant function. It's weird to describe but I swear by it.

I tried writing using Google Docs, but my writing ended up being bloated and waffly, and the overall blog post was pretty meh.

Notice that you only need to open the p tag, no need to close it. In HTML5, many tags are implicitly closed. This is very useful for lists and tables (no need to close i, tr, td). I actually prefer to write modern html directly by hand than to go trough the markdown filter du jour.

But why don't you activate a spell checker for your text editor?

I agree with pretty much the whole body of the article, but I dislike the title. IMHO one of the most important rules of writing is "know your audience, and write for them". When coding, your audience tolerates no ambiguity, has no sense of humour, and only understands simple commands. When writing, your audience has opinions, wants to be entertained, and feels love. So please don't literally write like you code!

Have to agree exactly. Fed up in academia having to help students who haven't swallowed a dictionary to do science. Extra verbiage when it's not exactingly explicit doesn't offer anything over a short succinct description.

I think there is far too much elitism over exacting English that makes papers as difficult to read as papers where there has been no oversight and no author who is a native speaker.

Good in this context seems to mean efficient at communicating ideas, but this is far from the only purpose of writing. Sometimes while writing one may want to obfuscate the meaning for certain readers like innuendo in childrens' media. It would be a tragedy if every novel was written in the style of Hemingway.

I like this book related to the subject.

https://www.penguinrandomhouse.com/books/198856/it-was-the-b...

Unless the author's intent is to simultaneously give advice about how to code, the essay could be improved by removing the references to coding.

For example: Good writing is like good code, it's simple, efficient, and structured.

Good writing is simple, efficient, and structured.

Programming targets the machine while writing can influence the heart.

Don't write for a machine.

I think it's the other way round: code like you write (or like you ought to be writing, anyway).

this is good advice for technical writing but not prose (faulkner would like a word with you! (see my comment here: https://news.ycombinator.com/item?id=28383626))

Reply on news.ycombinator.com