16 ms·

Write Like You Code

151 points by enigmatic02 5y ago

Tomminn 5y ago
My physics supervisor used to tell me: "Write in Fourier space, starting at zero frequency and working your way up."
kranner 5y ago
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.
- blockwriter 5y ago
  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.
  - andrei_says_ 5y ago
    This sounds very interesting but I have trouble picturing it. Could you provide an example of text with this structure/rhythm?
  - sidedishes 5y ago
    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)
    - vpavicic 5y ago
      I enjoyed reading this very much! Thank you!
    - AstralStorm 5y ago
      And then Google Translate is applied and it all turns to mush or worse.
  - chrisweekly 5y ago
    Good point. Speaking of the art of writing good sentences, I heartily recommend "First You Write a Sentence" by Joe Moran.
- rTX5CMRXIfFG 5y ago
  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.
- hutzlibu 5y ago
  "- 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
  - bryanrasmussen 5y ago
    >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.
    - hutzlibu 5y ago
      "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.
- JamilD 5y ago
  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.
  - pbronez 5y ago
    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.
  - tuatoru 5y ago
    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.
- strogonoff 5y ago
  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.
- munch117 5y ago
  Also Mark Twain: "I never write metropolis for seven cents because I can get the same price for city."
xcambar 5y ago
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).
nathell 5y ago
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.
notRobot 5y ago
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/drunk_post_things_ive_learned_as_a_sr_engineer/ https://www.reddit.com/r/ExperiencedDevs/comments/nmodyl/dru...
open-source-ux 5y ago
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 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/ 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
- pkolaczk 5y ago
  “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
  - gnuvince 5y ago
    That quote is not by Knuth, it's from Abelson and Sussman: https://mitpress.mit.edu/sites/default/files/sicp/full-text/book/book-Z-H-7.html 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.
tinyprojects 5y ago
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.
- enriquto 5y ago
  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?
praptak 5y ago
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.
- KineticLensman 5y ago
  > 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.
  - erwincoumans 5y ago
    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).
    - KineticLensman 5y ago
swiftcoder 5y ago
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.
zaptheimpaler 5y ago
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 https://aphyr.com/posts/341-hexing-the-technical-interview http://scholar.harvard.edu/files/mickens/files/thenightwatch.pdf 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.
- jaza 5y ago
  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.
  - zaptheimpaler 5y ago
    I'm glad you liked them! Spread the word :D
codingdave 5y ago
> 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.
- m4r35n357 5y ago
- PopAlongKid 5y ago
  I see the irony of your comment.
slaymaker1907 5y ago
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.
KaiserPro 5y ago
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-writing/ 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"
jaza 5y ago
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!
barrkel 5y ago
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.
- fullstackchris 5y ago
  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.
thenerdhead 5y ago
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.
mhb 5y ago
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.
fullstackchris 5y ago
> 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.
- bitexploder 5y ago
  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.
- azangru 5y ago
  > 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>`
gnuvince 5y ago
My favorite writing lecture is this one: https://www.youtube.com/watch?v=aFwVf5a3pZM 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.
deltaonefour 5y ago
Programming targets the machine while writing can influence the heart. Don't write for a machine.
jcgoette 5y ago
I like this book related to the subject. https://www.penguinrandomhouse.com/books/198856/it-was-the-best-of-sentences-it-was-the-worst-of-sentences-by-june-casagrande/ https://www.penguinrandomhouse.com/books/198856/it-was-the-b...
rob_c 5y ago
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.
tpoacher 5y ago
I think it's the other way round: code like you write (or like you ought to be writing, anyway).
greenie_beans 5y ago
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 https://news.ycombinator.com/item?id=28383626))
kazinator 5y ago
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.

151 points by enigmatic02 5y ago

My physics supervisor used to tell me: "Write in Fourier space, starting at zero frequency and working your way up."

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.

blockwriter 5y ago
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.
- andrei_says_ 5y ago
  This sounds very interesting but I have trouble picturing it. Could you provide an example of text with this structure/rhythm?
- sidedishes 5y ago
  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)
  - vpavicic 5y ago
    I enjoyed reading this very much! Thank you!
  - AstralStorm 5y ago
    And then Google Translate is applied and it all turns to mush or worse.
- chrisweekly 5y ago
  Good point. Speaking of the art of writing good sentences, I heartily recommend "First You Write a Sentence" by Joe Moran.
rTX5CMRXIfFG 5y ago
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.
hutzlibu 5y ago
"- 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
- bryanrasmussen 5y ago
  >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.
  - hutzlibu 5y ago
    "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.
JamilD 5y ago
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.
- pbronez 5y ago
  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.
- tuatoru 5y ago
  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.
strogonoff 5y ago
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.
munch117 5y ago
Also Mark Twain: "I never write metropolis for seven cents because I can get the same price for city."

xcambar 5y ago

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).

nathell 5y ago

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.

notRobot 5y ago

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/drunk_post_things_ive_learned_as_a_sr_engineer/ https://www.reddit.com/r/ExperiencedDevs/comments/nmodyl/dru...

open-source-ux 5y ago

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 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/ 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

pkolaczk 5y ago
“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
- gnuvince 5y ago
  That quote is not by Knuth, it's from Abelson and Sussman: https://mitpress.mit.edu/sites/default/files/sicp/full-text/book/book-Z-H-7.html 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.

tinyprojects 5y ago

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.

enriquto 5y ago
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?

praptak 5y ago

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.

KineticLensman 5y ago
> 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.
- erwincoumans 5y ago
  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).
  - KineticLensman 5y ago

swiftcoder 5y ago

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.

zaptheimpaler 5y ago

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 https://aphyr.com/posts/341-hexing-the-technical-interview http://scholar.harvard.edu/files/mickens/files/thenightwatch.pdf 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.

jaza 5y ago
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.
- zaptheimpaler 5y ago
  I'm glad you liked them! Spread the word :D

codingdave 5y ago

> 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.

m4r35n357 5y ago
PopAlongKid 5y ago
I see the irony of your comment.

slaymaker1907 5y ago

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.

KaiserPro 5y ago

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-writing/ 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"

jaza 5y ago

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!

barrkel 5y ago

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.

fullstackchris 5y ago
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.

thenerdhead 5y ago

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.

mhb 5y ago

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.

fullstackchris 5y ago

> 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.

bitexploder 5y ago
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.
azangru 5y ago
> 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>`

gnuvince 5y ago

My favorite writing lecture is this one: https://www.youtube.com/watch?v=aFwVf5a3pZM 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.

deltaonefour 5y ago

Programming targets the machine while writing can influence the heart. Don't write for a machine.

jcgoette 5y ago

I like this book related to the subject. https://www.penguinrandomhouse.com/books/198856/it-was-the-best-of-sentences-it-was-the-worst-of-sentences-by-june-casagrande/ https://www.penguinrandomhouse.com/books/198856/it-was-the-b...

rob_c 5y ago

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.

tpoacher 5y ago

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

greenie_beans 5y ago

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 https://news.ycombinator.com/item?id=28383626))

kazinator 5y ago

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.