5 ms·
Technical documentation isn't the place for a joke full stop. Documentation is for people who are typically busy, uncertain and potentially dealing with somethi
by roenxi 9y ago
Technical documentation isn't the place for a joke full stop. Documentation is for people who are typically busy, uncertain and potentially dealing with something that is going wrong.
They want clear, concise and accessible help. They don't want or need tasteless jokes. It is disrespectful to their time to include random garbage.
This is supposed to be read by people who need it, not people who know what is going on and want to enjoy a good laugh.
- thiagoharry 9y agoThe TexBook was a technical documentation for TeX written by Donald Knuth. The book had a lot of jokes, and I enjoyed reading it.
- geofft 9y agoLeaving aside the question of the nature of its jokes, the TeXBook is the sort of thing you read straight through. It's a narrative about how some code came to be. It's not the same sort of reference as the glibc manual, and I think a narrative form of documentation benefits from a casual tone and a four-sentence standalone reference about a function (especially where one of those sentences is "Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt") benefits from a terse tone.
- hapnin 9y agoKnuth is actually funny.
- chillingeffect 9y agoWe're humans, not robots. We don't run on information alone.
- analogmemory 9y agoHey meatbag, even robots like a good joke
- __s 9y agoYeah, Python docs need to stop using variable names like 'spam' & 'eggs', Monty Python's too jokey, no room for it in docs
- djsumdog 9y agoI think that's a little different. Even with the fun variable names, the Python docs are pretty damn professional. They haven't always been that way. The Python docs back around 2000 were not that great. A lot of work has been put in by people in the community to get them to the state they're in.
- dfox 9y agoPython docs are very good and professional, but somewhat chaotic unless you have pretty good grasp on what belongs where. Just last friday I tried to find authoritative definition of the leading underscore mangling behavior in the docs and was not able to do so.
- geofft 9y agoIf you genuinely believe that these are comparable situations (and you're not just making a strained comparison to argue in favor of the side you favor), I'm not sure how to explain my position to you. Although I think I would start by saying this: where "spam" and "eggs" is used in Python, it is in the place of any other word, usually a nonsense word like "foo" or "bar", and its presence does not distract. I doubt anyone thinks of actual SPAM or actual eggs when they run across it, and I seriously doubt the documentation authors intended or expected anyone to. The (so-called) joke in this glibc discussion is a) essentially a pun on the name of the function, i.e., introducing mental confusion; b) a political subject; c) an ill-explained reference to a political subject (did you know it's about the global gag rule? do you know what the global gag rule is?); d) intended to make you think about that subject instead of tuning it out. Python's use of "spam" and "eggs" adds some character, that's about it. (Python's insistence on "eggs" and "wheels" and "cheeseshop", on the other hand... I find the names cute but if you wanted to get rid of them all in favor of slightly more descriptive words, I'd honestly be in favor.) This joke serves no purpose other than, at best, to distract the attention of the person looking up documentation onto a completely different subject.
- deleted 9y ago[deleted]
- djsumdog 9y agoI'm not that hardcore about it, but I still agree this really shouldn't be in the official docs. Maybe in a tutorial or a set of slides. I do agree with some professionalism in things that want to be taken seriously. I don't even really like the "Apt with super cow powers." I do agree this isn't about political correctness. At one time GNU tools were just a bunch of devs trying to write open source tooling for fun or to learn. But with it being such a huge part of our industry now, it does need to grow up. If you're working on your own small open source projects, have fun with the docs and comments. But don't be like Stallman. Realize if your tools are really successful, those quips might get cut out one day. c'est la vie
- dfox 9y agoMy feeling is that most of GNU manuals in texinfo format are borderline useless because the structure is simply wrong, the random jokes are somewhat tangential issue.
- sandov 9y agoI Don't know if we're talking about the same thing but I've found the format of man pages to be absolutely useless for me. Maybe I'm too dumb/noob to understand them, but then what's left for the folk who just switched to linux and wamts to learn about commands.
- grzm 9y agoTexinfo and man are different. https://en.wikipedia.org/wiki/Texinfo https://en.wikipedia.org/wiki/Texinfo > "Notably, man is not available as an output format from the standard Texinfo tools. While Texinfo is used for writing the documentation of GNU software, which typically is used in Unix-like environments such as GNU/Linux, where man pages are the traditional format for documentation, the rationale for this is that man pages have a strict conventional format, used traditionally as quick reference guides, whereas typical Texinfo applications are for tutorials as well as reference manuals. As such, no benefit is seen in expressing Texinfo content in man page format. Moreover, many GNU projects eschew man pages almost completely, referring the reader of the provided man page (which often describes itself as seldom maintained) to the Info document." https://en.wikipedia.org/wiki/Man_page https://en.wikipedia.org/wiki/Man_page They can take some getting used to if you're not familiar with them, but given how much documentation is available in these formats, it's worth taking a few hours to become accustomed to them. A lot of it is duplicated online as well, so you can often use your favorite search engine.
- pishpash 9y agoThe early days of computing was very informal and full of jokes. Didn't stop people from creating some of the most long-lasting and technically successful tools.
- TeMPOraL 9y agoMaybe even helped them. Those tools create in informal atmosphere seem much more robust and useful than what the present day brings.
- jonhendry18 9y 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 9y 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 9y 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 9y agoFor what it's worth, that only high quality jokes bit made me laugh more than Stallman's joke.
- stronglikedan 9y 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.
- keiyakins 9y agoA well-constructed joke can make documentation more useful. I can't think of an example off the top of my head, but there've been plenty of times that something made me laugh and go "NOW I get it!" to the technical material. This isn't a well-constructed joke in that sense - it's likely to cause confusion, not increased understanding.