4 ms·
"Technical documentation isn't the place for a joke full stop" This is a bad take. When wading through dry technical documentation a little humor can make it m
by jonhendry18 8y ago
"Technical documentation isn't the place for a joke full stop"
This is a bad take. When wading through dry technical documentation a little humor can make it much less laborious.
As long as the humor doesn't result in ambiguity, there's no problem.
Something like "You can tune a filesystem, but you can't tune a fish." at the end of a manpage may elicit a chuckle but doesn't reduce understanding.
- rtpg 8y agoYeah, it should probably be more "your technical documentation should have a consistent tone" I appreciate light-hearted asides in documentation. But more if I expect it than when it's unexpected. Like you wouldn't want to end up confusing some ESL programmer who goes ask a lawyer whether they should be worried about this? Or if you're really ambitious, make all your docs super funny! But if you mix the tone it's disorienting and maybe bad writing.
- geofft 8y agoFor what it's worth, at least one member of the glibc steering committee appears to agree: "I agree with removing this joke. A bit of humor is fine - indeed, the manual could use a bit more than it has - but this attempt at humor does not work. The manual should be high-quality, and that includes high-quality jokes." https://sourceware.org/ml/libc-alpha/2018-04/msg00604.html https://sourceware.org/ml/libc-alpha/2018-04/msg00604.html
- humanrebar 8y agoFor what it's worth, that only high quality jokes bit made me laugh more than Stallman's joke.
- stronglikedan 8y ago> a little humor can make it much less laborious Here, here! I would even go so far as to say that Why's (Poignant) Guide to Ruby directly contributed a great deal to Ruby's popularity because of the witty content alone.