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?<p>Oh, and the author misspelt "sesquipedalian".<p>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.
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:<p>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.<p>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.
Good writing is utilitarian. Boring but it serves the purpose of communication.<p>Great writing is much more. It communicates and entertains. Here are 2 of my favorites relating to computerz:<p><a href="https://aphyr.com/posts/341-hexing-the-technical-interview" rel="nofollow">https://aphyr.com/posts/341-hexing-the-technical-interview</a><p><a href="http://scholar.harvard.edu/files/mickens/files/thenightwatch.pdf" rel="nofollow">http://scholar.harvard.edu/files/mickens/files/thenightwatch...</a><p>Although I do agree the advice does make sense for most of us, who just aren't very good at writing. But if you <i>do</i> 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.
The advice should not be a rule of thumb.<p>Fortunately not every communication has for sole purpose to transmit information efficiently. Most communication indeed are not an elevator pitch nor should be BLUF.<p>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.<p>Should I want to extend the article to absurd limits, it could read "do not write poetry nor prose".<p>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.<p>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.<p>Even modern programming languages have terrible compiler error messages. (Rust has made a commendable effort to display readable English compiler error messages.)<p>All this suggests to me that developers who write their English like their code are writing like a computer, not writing for other humans.<p>---<p>Here are two recommendations for writing clear English (excludes fiction) :<p><i>Plain English Campaign</i><p>This is a campaigning organisation from the UK which promotes clear, easy-to-understand written English suitable for any industry or profession.<p>Here is their clear, simple and short guide on How to write in plain English [PDF]:<p><a href="http://www.plainenglish.co.uk/files/howto.pdf" rel="nofollow">http://www.plainenglish.co.uk/files/howto.pdf</a><p>---<p><i>GOV.UK: 10 tips for clear writing</i><p>I find the tips at the following link very helpful:<p><a href="https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/" rel="nofollow">https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/</a><p>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:<p>1. Establish ‘The Point’<p>2. Write it like you’d say it<p>3. Don’t try to sound clever<p>4. Show the thing<p>5. Know that you are not your writing<p>6. Share your work<p>7. Read (poetry in particular)<p>8. Never start with a blank page<p>9. Know when enough is enough<p>10. Stay human
My favorite writing lecture is this one: <a href="https://www.youtube.com/watch?v=aFwVf5a3pZM" rel="nofollow">https://www.youtube.com/watch?v=aFwVf5a3pZM</a><p>The number one piece of advice: your writing can be clear and structured, but if it's not <i>valuable</i> it's useless and people will stop reading. If you want to write well, figure out <i>who</i> your readers are, figure out what they value, and give it to them.
> You don't need React for your landing page.<p>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.<p>_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.<p>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.
> Novice writers use big words to hide their own lack of understanding, similar to how novice programmers use frameworks.<p>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.
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:<p>"Drunk Post: Things I've learned as a Sr Engineer": <a href="https://www.reddit.com/r/ExperiencedDevs/comments/nmodyl/drunk_post_things_ive_learned_as_a_sr_engineer/" rel="nofollow">https://www.reddit.com/r/ExperiencedDevs/comments/nmodyl/dru...</a>
To me Orwell's guide to writing seems to be the best mix of practical and style: <a href="https://infusion.media/blog/george-orwells-six-rules-for-writing/" rel="nofollow">https://infusion.media/blog/george-orwells-six-rules-for-wri...</a><p>Short, concise and to the point.<p>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.<p>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.<p>Those documents are a pain for most people to read, though.<p>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.<p>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.<p>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!"<p>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.<p>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.<p>Great writing uses fresh, vivid and appropriate analogies. Making up new stuff in code is more often than not the wrong thing to do.<p>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.
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).<p>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).<p>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.<p>Mind Maps/Whiteboard Ideas -> Outlines -> First draft -> Self Edit -> Professional Edit -> Publication<p>Each of these steps is similar to a high-level design which can have the biggest optimizations.<p>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.<p>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.<p>There's no spellchecker, it's annoying wrapping paragraphs in <p> tags, but my quality of writing is 10x better.<p>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.<p>I tried writing using Google Docs, but my writing ended up being bloated and waffly, and the overall blog post was pretty meh.
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.<p>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.<p><a href="https://www.penguinrandomhouse.com/books/198856/it-was-the-best-of-sentences-it-was-the-worst-of-sentences-by-june-casagrande/" rel="nofollow">https://www.penguinrandomhouse.com/books/198856/it-was-the-b...</a>
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.<p>For example:
<i>Good writing is like good code, it's simple, efficient, and structured.</i><p>Good writing is simple, efficient, and structured.
this is good advice for technical writing but not prose (faulkner would like a word with you! (see my comment here: <a href="https://news.ycombinator.com/item?id=28383626" rel="nofollow">https://news.ycombinator.com/item?id=28383626</a>))