Hacker News Reader

Comment by gaze | Hacker News Reader

There is this writing style that seems prevalent around certain programming circles, particularly the JavaScript, Python, and Ruby communities. It’s informal and somewhat hammy—- perhaps to seem friendly and more approachable. I imagine it’s pretty fun to write this way. Do people find it easier to read?

View on HN

I think it's fair to say it was pioneered by why's (poignant) Guide to Ruby [0].

Spolsky is a fan of the style. He's made the case for deliberately writing documentation that's fun to read, rather than using a dry style. As he puts it, nobody read the spec, because it was so dang mind-numbing. [1]

[0] https://en.wikipedia.org/wiki/Why%27s_(poignant)_Guide_to_Ru...

[1] https://www.joelonsoftware.com/2000/10/15/painless-functiona...

There was writing like this considerably earlier, e.g, Leo Brodie’s Starting FORTH https://www.forth.com/starting-forth/

And Helmut Zwittlinger’s Comic Pascal https://balancedaction.files.wordpress.com/2016/03/img_0091....

Please don't follow Joel's advice. He's taking the wrong lesson. You can be conversational, you can lade your document with copious real world examples and justifications for rules, and illustrations, and explaining how different parts of the spec interact, and warn about common mistakes and included FAQs, but don't fill it with distracting unfunny garbage like Miss Piggy poking at a keyboard with eyeliner because her fingers are too fat.

The documentation can be enjoyable... the spec I think should be dry as a cracker. But if you want to write enjoyable docs, write like John Carlos Baez writes math/physics paper. The enjoyability should serve the clarity. Anything else is superfluous.

Depending on the circumstances, I often do. For a big topic like this, part of the reason I like it is that the pacing is better. It tends to be less densely packed, and lets me read through something carefully but not feel too strained. It also has a story, if you will, that helps me get back on track later on if I'm sticking with it. It's not to say a more formal style of writing couldn't achieve similar goals, but I just find they don't tend to.

There are plenty of scenarios where it wouldn't fit (references, specifications, etc) of course. So I don't think it's great everywhere. But yeah, overall I find it easier to read when starting out on a big topic.

Personally I found that style funny for a while but now I feel it's becoming tedious and won't age well. In the long run I prefer a style like Kernighan & Ritchie which is concise, easy to read and timeless.

Yeah, it's like hearing a ukulele and a folksy male voice in a TV commercial. It's been done, move along.

I too prefer barely more than "just the facts" that are relevant to the document's audience and purpose.

> perhaps to seem friendly and more approachable.

nothing makes me press ctrl-w faster that a web page that tries to be "friendly" (in an american pop-culture way) with me.

Do you ctrl-w before or after the first animated gif meme?

i also ctrl-w if something takes more than a couple seconds to load, which is most gifs, even on a gigabit fiber connection <_<

we did this book for our work book club a year or so ago. most people in the club enjoyed reading it. there were issues getting the some of the examples to work at the time but that's another matter.

Reply on news.ycombinator.com