5 ms·
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 doc
by MaxBarraclough 7y ago
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_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.