Hacker News Reader

Comment by cycloptic | Hacker News Reader

Yes, many times, but I don't see how that is relevant. Technical documentation is not a comedy performance, you read it to learn how to use the product, not to develop your sense of humor. Why would there be jokes in there made at the expense of any group? Within the documentation, it makes perfect sense for these projects to ban any of these kind of jokes that could anger people, if what you really want is cynical hot takes and snarky jokes, there seems to be no shortage of that on HN and Twitter and other places that aren't technical documentation.

View on HN

Could not possibly disagree more. The tech industry has always had humor lurking around. Easter eggs, little jokes. BeOS wrote their error messages in Haiku. It was a lot of these little things that endeared you too a product.

Communication and engagement often require some humor. The first programming book that helped me grok programming was full of humor and stupid cartoon drawings.

And let us not forget Godot is open source. People do this for fun and put in their own time and effort. I don’t think anybody should really be telling them what they can and cannot be doing while pursuing their passion for your benefit.

The constant stream of little quips and inside jokes that endear you and I to things also can be off-putting and drive outsiders away. I am sorry but I've spent my years explaining so many strange things that nobody understands like "Guru Meditation," and it's not really funny any more when you have to keep explaining the joke. And those are just the little innocent gags, it's much much worse when the joke is disparaging someone.

It also doesn't seem like this was written by some random open source contributor, it seems it was done by the maintainers, who are being paid to work on it by their patrons. They absolutely do have to answer to those patrons. While people seem to like to assign all blame for things on twitter commentators for whatever reason, it's likely the actions they took are the result of feedback from the patrons.

> I am sorry but I've spent my years explaining so many strange things that nobody understands like "Guru Meditation," and it's not really funny any more when you have to keep explaining the joke.

New people are born every day and we have to explain to them a lot of well-known things, again and again. This is how everything works, not only humor. I do not want to lose great things like "guru meditation" just because some people like you are tired of explaining them.

I don't know you mean by lose, the original Guru Meditation is already long gone. If you have your own thing and you want to keep the joke alive by spending your time fielding a bunch of support requests from confused users asking what "Guru Meditation" means then be my guest, I can't take that away from you.

My feeling is just that if you change that message from "Guru Meditation" to "you are an ass hat" or something rude like that, you will probably get many more complaints.

> And those are just the little innocent gags, it's much much worse when the joke is disparaging someone.

This may be a stupid question, but why is it such a bad thing that they are disparaged? Maybe Godot doesn't want them as patrons, and are they even contributing that much?

Humour is humour, and shouldn't be limited only to designated stages. I personally enjoy technical documentation or even math books that contain humour. I'd even say it's quite common in the geek culture, so I'm not sure what your opinion is based upon.

Sometimes I do enjoy that too, but I can also see how other people don't enjoy that type of humor and wouldn't want to be subjected to being mocked. You can't force people to think a joke is funny especially if you're intentionally doing it outside one of those designated stages, often the context is the entire reason the joke is funny. It's one thing if you're picking between 100 math books on the same subject, and you pick one of them that contains the humor that you like, but that's different from when you're shipping the official documentation which is supposed to be the one source of truth for the project. Users can't just pick a different book there if they find your jokes off-putting.

> Sometimes I do enjoy that too, but I can also see how other people don't enjoy that type of humor and wouldn't want to be subjected to that.

How is anyone subjected to it? No one is being forced to read anything. It is wrong to remove text in the anticipation of the possibility of someone coming along and being offended by it.

As far as I can tell people are being forced to read it if they want to learn that particular API. It wasn't some third party blog or tutorial. (Please correct me if I am wrong about this)

You are unlikely to need to read that part of the API unless you want to mess with a very specific feature (encryption in save files).

Even then, text (as a format) allows you to easily skip to parts you care about. If I was looking for docs on this API, I'd skip to examples and read paragraphs above them if code is unclear.

I also wholeheartedly disagree with your stance that there is a time and place for humour: humour is for every occasion (and I know of cases where it was successfully applied in the saddest of moments, someone losing a loved one)!

You are also guilty of assuming that someone is offended where you are not! Sensitivity and empathy are needed, but we can't hear from the really offended ones because people who are offended in their stead just add the noise.

I still upvoted your comments because I also disagree with downvotes being used for disagreement :)

Why are you making normative claims about technical documentation? That seems to me more preposterous than anything written in the mentioned piece.

I'm not sure what you mean, the entire point of technical documentation is that it explains a technical subject, that is the definition of the phrase. You could add other things but then it stops being just that.

No, it doesn't "stop being that". You're going to have to provide some sort of justification for that statement.

I said it "stops being just that." You removed the word "just" which changes the entire meaning of the sentence.

Sorry, one can read "just that" in two ways there, "it at all" or "only".

To carry on with your intended meaning, what is the problem if the technical documentation is more than just technical documentation? We're talking about a paragraph here, maybe 0.1% of the documentation. Are you making a claim that at some percentage of non-technical content the documentation becomes illegitimate?

I'm honestly just trying to understand what you're getting at.

Possibly I should have said "it stops being only that," that might have been more clear. The problem with making that 0.1% into something else is that people still get annoyed and distracted by it because it's not what they expected, and they complain, which is exactly what happened here.

> the entire point of technical documentation is that it explains a technical subject

It also becomes incredibly boring. I hear what you're saying, but work has to be fun, at least sometimes.

> Technical documentation is not a comedy performance,

Maybe not for you! Some of the clowns I've had to work with ....

Reply on news.ycombinator.com