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

31–40 of 71 posts

Re: Write Like You Code

#31

Post by jaza »

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.

Re: Write Like You Code

#32

Post by unbanned »

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

The problem comes since this doesn't make it seem like you have a wide vocabulary. A large vocabulary is naively indicative of intelligence; why you'll see inexperienced people using flowery complex language in a multitude of different ways to explain the same ideas..... Certainly proliferated from American English. Annoying.

Re: Write Like You Code

#33

Post by jaza »

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!

Re: Write Like You Code

#34

Post by AstralStorm »

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…

And then Google Translate is applied and it all turns to mush or worse.

Re: Write Like You Code

#35

Post by pkolaczk »

open-source-ux wrote: post #12

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…

“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

Re: Write Like You Code

#36

Post by barrkel »

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.

Re: Write Like You Code

#37

Post by thenerdhead »

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.

Re: Write Like You Code

#38

Post by ljm »

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 applies quite generically to coaching as well: if the person you're listening to uses a certain word to describe something, continue to use that word yourself instead of trying to paraphrase it.

In that sense, you're sticking to one word for a concept, but the word is given to you by someone else. And by using their terminology and not your own refactoring, you are making sure that you're not distracting them from their own thinking.

Re: Write Like You Code

#39

Post by gnuvince »

pkolaczk wrote: post #35
open-source-ux wrote: post #12

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…

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

Re: Write Like You Code

#40

Post by kqr »

marcellus23 wrote: post #30
kqr wrote: post #19

Earlier quoted context omitted.

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.

Aha! I never dug deep enough into the issue to learn that. Thanks!

Is there a name for the phenomenon I'm referring to?

Post reply on HN