Issue with pdoc pages

[cocodedesigns]

I understand that this is not related to pdoc3, but it does relate to the pdoc3 docs page. I also know that some people will jump on and accuse me of being "too sensitive" and "politically correct", but to be honest I don't care anymore. This is important to me.

On your GitHub pages site, you have included a quote talking about the importance of documentation. However, your quote of choice compares the inclusion of documentation to sex. It implies that bad sex is better than no sex, which I find to be incredibly harmful. Clearly, for a lot of men, the idea that a bad sexual experience is better than no sexual experience is pervasive and is seeped in everywhere, but for a lot of women, a bad sexual experience is being raped. While I know you haven't used the quote to diminish that, it's not exactly a good quote to be using.

I understand that you're wanting to show the importance of documentation, even bad and incomplete documentation. I understand, it's vital to have documentation for your project, but there are many better quotes than that one. Just from a thirty second Google search, I found a few:

"Documentation is a love letter that you write to your future self." -- Damian Conway
"Lack of documentation is becoming a problem for acceptance." -- Wietse Venema
"I think that the richer and deeper documentation is on the web, the better off we all are." -- Kenneth Goldsmith
"I guess it’s better to have too much information than too little. It makes the manufacturer feel good, keeps writers employed, and makes attorneys work a little harder. Besides, it gives me something to read as I'm eating those chewy white peanuts that came with my new computer." -- Dave Glardon, writer, comedian and actor.

There are four, just from a cursory search, that I think are far better than the one you have used there and don't touch on a pretty sensitive topic. Again, I get the intent behind the quote, but for some people, it can be upsetting. Not only that, but there will be some people who use pdoc and will read that and laugh explicitly because they agree with it in that context - that rape is nothing more than bad sex, and survivors should consider themselves lucky that they're getting some.

It might not be an issue to you - it may have zero impact on you whatsoever - but it is to me and I know others for whom this is also an issue. Please, reconsider the use of this quote. I believe you used it in good faith and with the best of intentions, but there will be someone who will read it who will laugh because they see it in that context and someone else who will feel that you couldn't care less about it.

[KarenJewell]

I agree with this completely. To survivors of sexual assault, many of whom who are women but also many men, bad sex is not better than no sex. The idea that we would reinforce people to pursue sex even if it was a bad experience for all parties, really terrifies me. Nobody really wants that.

Please consider dropping the "bad sex" quote from the docs page. It is unnecessary, leaves a really bad taste, and distracting from what is actually important on there. I vote for the love letter quote to replace it instead.

[jjoocceeee]

This change is long overdue. I think about how inappropriate this quote is every time I use pdoc.

There are many other quotes that can be used to show the importance of Documentation. A quote about bad sex is not the correct way to go about this.

[IrinaMaria]

I agree with all of the above. There is no need for these quotes to be promoted (so many better options are available). Also is it worth it at the risk of causing upset to others? I hope to see this changed. Well, done to those who are calling this out.

[sprigles]

I'll add my agreement with the above. It's a quote in poor taste that detracts and distracts from the point being made. There is no harm in removing it, but plenty of harm to be caused by leaving it.

[kevinmanncito]

Agreed, there are better ways of getting the point across. It's not a funny quote.

[kernc]

Tangentially, might one of you empathetic warriors point out the link you all followed to end up commenting here in the observed succession?

[sprigles]

The link? Hmm... 🤔 Let's go with "common decency".

[KarenJewell]

@kernc https://pdoc3.github.io/pdoc/

[cocodedesigns]

With respect, @kernc, does it ultimately matter? Understand that this is not some kind of "coordinated attack by the Wokerati" or something, and I took great pains to get that across. I understand why you went for that quote. It is important to have some kind of documentation for your project rather than none at all, even if it's badly documented. I get that concept and I agree. I've fallen foul of that myself in my own projects, and the idea is right. This project has actually put in place plans to change that across all of my projects, because it is important to have some kind of documentation for your work so that others can understand how to use it and how to build on it. It's essential to the furthering of tech and software development. You can convey that without using that quote, though. I get the principle you want to pass on, but I don't get why you chose that over every other method of demonstrating it.

Let me put it to you this way: You make any kind of comment about any kind of hot button topic. For the sake of this, let's use sexual violence because it's where we're circling. It can be a joke, a quote, an offhanded comment, something that lends itself to the topic in a tangential way, whatever. It can talk about sexual harassment, sexual assault, rape, anything in between, your choice. For the sake of this, it ultimately doesn't matter what your choices are, because the same thing will happen: Two people will hear your comment:

1. Someone who survived an attack, and
2. Someone who attacked a survivor.

You can argue there's a third group, but they will ignore what you said and will go on without a care in the world either way. These two are the ones who will pay attention to what you said, and one of them will look to you and say "They get me. They know what I'm talking about. They understand me. They speak my language. They said that in a way I never could. They speak to me." Which of those people would you want to say that about you? The abuser or the abused?

You might see that as dramatic, but ultimately someone will read it and see that. That quote that you put does little to emphasise a point in the grand scheme of things, and there are a myriad of other ways that this point can be achieved to the same effect or better. You can get across the importance of documentation without referring to sex in any capacity, good or bad. That quote equates bad documentation (which can still be incredibly useful) to bad sex (which can be incredibly harmful and hurtful). It is unnecessary to use it, especially given that there are plenty of other ways that you can get this same point across. I found a few on a quick Google search.

The point is, there are people that have read the quote in question and seen something that has either offended them or they think could offend someone else, probably someone they know, someone that survived an attack. We have looked at it and seen there are plenty of other ways to convey the exact same point that wouldn't do any harm to anyone. All we ask is that you change the quote or remove it and replace it with something that still drives home the point you are trying to make. Using that quote is, at best, dismissive and simplistic, and at worst, incredibly harmful, depending on who reads it. The person who reads it will hear you say it. It's in your documentation.

At this point, it's your call. This is your project, you have been involved in it heavily. Whether you take action or not is up to you, it is entirely your decision. Personally, I don't see why changing it would cause that much of a problem. Again, there are plenty of ways to convey the same point. Why does it need to be with that quote? If you can get that same point across in another way, arguably more effectively in some cases, why do you have to stick with that one particular way? At a certain point, the only possible remaining answer is "Because I like it" and that says a lot more than you would intend it to.

Again, it's your call now. I've raised the issue. Others have agreed with it for their own reasons. This is now on you.

[zenjen-devs]

Tangentially, might one of you empathetic warriors point out the link you all followed to end up commenting here in the observed succession?

Perhaps the (em)pathetic warrior for people deprived of "good" sex should not be tangentially concerned where the link was shared. To second the above reply, it really does not matter.

[okuboshigeo]

It seems that the footer of the pdoc website also contain nazi symbols:

See https://github.com/mitmproxy/pdoc#pdoc-vs-pdoc3 :(

[cocodedesigns]

To reference the previous comment (thank you @okuboshigeo for raising it, as I had not noticed that)

1. The Nazi bastardisation of the swastika and the original use are often indistinguishable, especially without additional design elements. On its own, without context, without colours anything else, they can be viewed as one and the same. I understand that your intent is to help reintroduce its original context, but that icon is too far ingrained into the psyches of some people as the iconography of the racists and the far right. Trying to reintroduce it based on its origins may be more work than necessary, and your use on the page doesn't seem to be doing that. I'd suggest rethinking the use or removing it entirely, as it can reflect badly on you. I understand your intent, but it's not coming across the way you would hope.
2. Even with that particular point aside, the quote you included in the footer is, I believe, far better than the one at the top of the page. It drives home the point of the need for documentation without needing to resort to sexual metaphors. Would it be worthwhile, then, to remove the icons and replace the "bad sex" quote with the one in the footer? You can then use the footer to reference the original repo and devs there for providing the foundation for your own project, or something else.
3. I didn't notice this on my laptop but did on my phone - there are quite a few adverts on the page, including what I believe are AdSense adverts. My laptop has AdBlock installed so they don't show there, but my phone's default browser obviously does not. I believe that GitHub, while it doesn't explicitly condemn the use of adverts, does frown upon the use of adverts in what could be conceived as excessive context. It supports sponsorship and some other mechanisms for financing projects. Someone on another forum had a query about adverts and posted that a representative of GitHub replied:

The content of Pages is at the user's discretion, as long as it's legal and doesn't otherwise violate the Terms of Service. Some users may choose to include ads, donation buttons, ticket sales, or other ways of monetizing their projects, and that's OK with us. Of course we hope folks will Keep It Classy™ and use this power for awesome! Thanks

I'd look to review the number of adverts you have on the page if I were you, in case GitHub cries foul. They may not, you may be fine, but it's probably better to be safe than sorry.

Personally, I want your fork of the original pdoc project to be successful. We all do. I hope you understand that this purpose of this thread is about making it better for others and improving your project overall. These may be small changes, but they improve a lot overall.

[asierjon]

And you can see that the page is monetized. So that’s the reason he asked to share the link where this was seen, so he can make this a win. You got us chief. Very clever, coin warrior.