Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Write Like You Code

chrisbehan.ca

Post reply on HN
Print view View original

11–20 of 71 posts

Re: Write Like You Code

#11

Post by vpavicic »

sidedishes wrote: post #6
blockwriter wrote: post #4

Earlier quoted context omitted.

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 t…

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…

I enjoyed reading this very much! Thank you!

Re: Write Like You Code

#12

Post by open-source-ux »

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

Re: Write Like You Code

#13

Post by tinyprojects »

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

There's no spellchecker, it's annoying wrapping paragraphs in

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.

Re: Write Like You Code

#14

Post by praptak »

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.

Re: Write Like You Code

#15

Post by hutzlibu »

kranner wrote: post #3

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…

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

Re: Write Like You Code

#16

Post by KineticLensman »

praptak wrote: post #14

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…

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

Re: Write Like You Code

#17

Post by JamilD »

kranner wrote: post #3

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…

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.

Re: Write Like You Code

#18

Post by enriquto »

tinyprojects wrote: post #13

I write most of my blog posts using Sublime text directly into html code. There's no spellchecker, it's annoying wrapping paragraphs in 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 descri…

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?

Re: Write Like You Code

#19

Post by kqr »

praptak wrote: post #14

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…

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.

Re: Write Like You Code

#20

Post by swiftcoder »

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.

Post reply on HN