5 ms·

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 wou

by CA0DA 5y ago

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!

ljm 5y ago
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 5y ago
  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 5y ago
    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 5y ago
      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 5y ago
        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 5y ago
        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.
        autarch 5y ago
        I didn't use the words "triggered" or "micro-aggressions", so what exactly are you quoting? Saying "your project sucks" or "your project docs suck" is not a _micro_-aggression, it's a macro-aggression, or as I prefer, being a jerk. I think most people would react negatively to that sort of statement.
- deleted 5y ago
  [deleted]
esperent 5y ago
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 https://github.com/gohugoio/hugo/pull/6398
- CA0DA 5y ago
  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.

by CA0DA 5y ago

ljm 5y ago

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 5y ago
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 5y ago
  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 5y ago
    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 5y ago
      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 5y ago
        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.
        autarch 5y ago
        I didn't use the words "triggered" or "micro-aggressions", so what exactly are you quoting? Saying "your project sucks" or "your project docs suck" is not a _micro_-aggression, it's a macro-aggression, or as I prefer, being a jerk. I think most people would react negatively to that sort of statement.
deleted 5y ago
[deleted]

esperent 5y ago

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 https://github.com/gohugoio/hugo/pull/6398

CA0DA 5y ago
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.