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

61–70 of 71 posts

Re: Write Like You Code

#61

Post by munch117 »

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…

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

Re: Write Like You Code

#62

Post by rob_c »

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.

Re: Write Like You Code

#63

Post by derefr »

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

Re: Write Like You Code

#64

Post by pkolaczk »

gnuvince wrote: post #39
pkolaczk wrote: post #35

Earlier quoted context omitted.

“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 val…

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!

Re: Write Like You Code

#66

Post by zaptheimpaler »

jaza wrote: post #31
zaptheimpaler wrote: post #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…

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

Re: Write Like You Code

#68

Post by marcellus23 »

musingsole wrote: post #44
marcellus23 wrote: post #30

Earlier quoted context omitted.

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.

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.

Re: Write Like You Code

#69

Post by tuatoru »

JamilD wrote: post #17
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…

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.

Re: Write Like You Code

#70

Post by hutzlibu »

bryanrasmussen wrote: post #47
hutzlibu wrote: post #15

Earlier quoted context omitted.

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

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

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

Post reply on HN