4 ms·
There is this writing style that seems prevalent around certain programming circles, particularly the JavaScript, Python, and Ruby communities. It’s informal an
by gaze 7y ago
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?
- MaxBarraclough 7y agoI 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_Ruby https://en.wikipedia.org/wiki/Why%27s_(poignant)_Guide_to_Ru... [1] https://www.joelonsoftware.com/2000/10/15/painless-functional-specifications-part-4-tips/ https://www.joelonsoftware.com/2000/10/15/painless-functiona...
- microtherion 7y agoThere was writing like this considerably earlier, e.g, Leo Brodie’s Starting FORTH https://www.forth.com/starting-forth/ https://www.forth.com/starting-forth/ And Helmut Zwittlinger’s Comic Pascal https://balancedaction.files.wordpress.com/2016/03/img_0091.jpg https://balancedaction.files.wordpress.com/2016/03/img_0091....
- lonelappde 7y agoPlease 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.
- gaze 7y agoThe 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.
- pseudoramble 7y agoDepending 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.
- ethyreal 7y agowe 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.
- Ididntdothis 7y agoPersonally 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.
- a3n 7y agoYeah, 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.
- jcelerier 7y ago> 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.
- lonelappde 7y agoDo you ctrl-w before or after the first animated gif meme?
- jcelerier 7y agoi also ctrl-w if something takes more than a couple seconds to load, which is most gifs, even on a gigabit fiber connection <_<