Live data from Hacker News

Write Like You Code

chrisbehan.ca

21–30 of 71 posts

Re: Write Like You Code

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

Re: Write Like You Code

#22
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…

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.

Re: Write Like You Code

#23
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…

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

Re: Write Like You Code

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

Re: Write Like You Code

#25
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…

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

Re: Write Like You Code

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

Re: Write Like You Code

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

Re: Write Like You Code

#28
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…

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…

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

Re: Write Like You Code

#29

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

No post body was provided.

Re: Write Like You Code

#30
post #19
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 fairl…

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.
Post reply on HN