[CA0DA]

This gives a few good examples of how the Hugo documentation could improve (the click-bait word "Sucks" in the title is a bit exaggerated, in my opinion). I would challenge the author to, in the spirit of open source, go ahead and make some of the suggested changes and submit the changes in a Pull Request!

[esperent]

I have actually opened a pull requests [1] on the Hugo docs, adding one small sentence to clarify something that I was stuck on for several hours.

It was ignored for over a year, with the only comment being from me, then automatically marked stale and closed.

Needless to say I didn't open any additional PRs.

Also, this reflects my impression of the Hugo community in general - their discourse forum is pretty dismissive to questions (lots of "have you read the docs?" type responses when yes, I did read the damn docs, found them utterly confusing and that's why I spent 20 minutes writing up a detailed forum post to ask for advice).

[1] https://github.com/gohugoio/hugo/pull/6398

[CA0DA]

Huh, yeah that is disappointing.

I think the stale bot in Hugo repo is overly aggressive. I have had to "fight" the stalebot in the past by posting update messages.

[ljm]

The author could have saved a paragraph or two of preamble by choosing a less inflammatory title.

No need to write a disclaimer about best intentions unless you chose language that could rile people up.

[systemvoltage]

How would you suggest to write a title that’s less inflammatory?

I have a higher tolerance to this type of language. Some people find any critique offensive. Some embrace it.

With any public confrontation, you’re bound to get a spectrum of people with various reactions. How do we make sure criticism, even harsh, needs space in public dialog whether it is open source or not? If it’s meant with good faith, that is.

People these days have an adverse reaction to any sort of criticism and it is troubling. Anything other than a pat on the back and emojis is considered rude. We got rid of downvotes on YouTube and this was the justification.

[autarch]

Instead of "sucks", how about any of these:

* My Frustrations with Hugo's Documentation

* How Hugo's Documentation Confuses Me and How to Improve It

* Why I Don't Like Hugo's Documentation

The key thing I've done here in the first three is to reframe the criticism as an _opinion_ ("I", "me", "my") rather than an absolute ("it sucks").

I don't think it's too much to ask people to state their opinions _as opinions_ in cases where you know in advance that said opinion may lead to hurt feelings. These titles might _still_ lead to hurt feelings, but I think they're less likely to do so, and if they do then they will hurt less.

[systemvoltage]

Those are all great suggestions and that’s what I would use.

However, if you look under the facade, when talking to your colleagues and with people around you, “sucks” is very much a common, daily word.

This is the way I look at it. Sure, it’s not professional. But, the author is not trying to be professional I suppose. I am not going to debate it’s appropriateness.

I want to be clear, the point I’m debating is not about “sucks” per se, but any general criticism. Whenever you need disclaimers, it could mean two things 1) Rude or unacceptable title 2) Society expects unreasonable conformity and adherence to a particular language, set of values, etc.

In the case 2), we had a huge debate about “master vs main” branch. There are many examples.

We’d be better off dialing down the conformity and be more inclusive. Check in deeper about intentions and faith, than the facade of language. If the author used the language you suggested, but had bad intentions, that’s a bigger problem.

[autarch]

I don't think the issue is being professional or not. If the author's goal is to convince people who work on Hugo to improve the docs, then it's best to avoid triggering a defensive emotional reaction. The title as it stands will likely trigger hurt feelings, which is usually followed by being defensive or ignoring the substance of the criticism. That's simply unproductive.

[systemvoltage]

The only thing I agree here is that better language wouldn't hurt. I don't think most people get "triggered". That's a vocal minority perpetuating a culture demanding a sort of conformity against their definition of "micro-aggressions" and "triggers" with no regards to a larger consultation with the society.

[corobo]

It's a shame we can't peek into alternate universes to prove/disprove but I have to imagine those titles wouldn't have nearly as many upvotes

[autarch]

You're probably right, but I think not being a jerk should trump HN upvotes.

[dahdum]

As written it seems to me the intent of the article is to publicly shame the open source devs who contribute their time and effort into doing more work for free.

It's typical open source toxicity.

[chipotle_coyote]

This makes me think of the old programmer joke that's something like, "There's no documentation. If it was hard to write, it should be hard to understand."

In project like Hugo that has no "user interface" to speak of, tools for which you can't reasonably be expected to just look at the UI screens and figure things out if they're nicely done because there are no UI screens to look at, the documentation is the user interface. Full stop.

The article lays out exactly what its author doesn't like about the documentation and makes suggestions for improvement. The "your documentation sucks" title is the harshest thing about it, and if it was truly a rant I could see getting prickly about it, but it absolutely is not. This is constructive criticism. And that's just as important for an open source project as it is for any other project.

I get bristling at the "if you can't stand having your suggestions torn apart, then don't contribute to open source" weird macho mindset some projects have historically have. Yes, it's toxic. But "if your suggestion is not sufficiently deferential, away with you" goes too far in the other direction.