I never used Traefik and have no opinion on it one way or the other as such. But if this is the response to some criticism of the documentation – which you can agree or disagree with, then you've done more to turn me of from Traefik than anything anyone here can write.

Note that the commenter isn't associated with traefik itself

Right so; the way it was written implied that at least they had spent significant amount of time on it, at least to me (I tried a quick grep in "git log" to see if I could find them, but couldn't find anyone matching the username here).

Disagree that this isnt a generic problem. And i'll take the same amount of umbrage at you calling it disingenuous. There are dual needs here. Having to read a story and take in a wholly unrelated workflow just to discover only half of the switches available to the feature im looking up is a problem.

And when there isn't just straight documenting of what's been implemented then it is an unreasonable gate to usage which limits customers to only the flows imagined by the technical writer.

Which itself breeds this sort of refusal to participate. Either the end user is ungrateful and needs to express that gratitude through silence or there's a smug moderator who's read everything and knows which paragraph of which tutorial has the answer and harangues anyone asking with a link and a "why didnt you read sentence 5 of paragraph 2 of a tutorial written 2 years and 3 major versions ago?"

Yes, those are two different kinds of documents for two different audiences.

You need both a java doc style big 'ol list of every function and what they do, and a narrative/workflow/primer based section of you documention

Investing a lot of time and trying really hard is not the same as adding a lot of value. If your users don't find value in your documentation, saying "But we spent a lot of time on it!" doesn't really change anything.

And, to be clear, I have no idea if the person you're responding to's criticism is valid. But I also know that your response does not negate their criticism at all.

How about submitting a PR to improve the documentation instead of complaining about it?

This is why OSS looks like a cult at times. People are allowed to criticize your project and complain about it. They have no obligation to become a contributor. "Submit a PR" is such a conversation killer.

Customer: I can't find anything I'm looking for in your store.

Store: I spent a lot of time arranging things around in the store, if you can't find what you're looking for you can stop complaining and write signs for us.

Customer: Or I can just use your competitor who actually cares about their customers. ¯\_(ツ)_/¯

Except the relationship between stores, customers and competitors all revolves around money and doesn't make sense in this context.

The relationship around this is open source, users and alternatives. It may not be money but nobody writes open source for the github stars, they want users and if your users are frustrated they'll go to alternatives.

- Former Traefik user who now uses Caddy.

Your adversarialism isn't a good look. Users are allowed to have opinions, this does not mean they have maintain the work themselves.

I didn't use try Traefik's documentation, but the complains appear to be somewhat structural. Meaning a PR would need to possibly restructure at least part of the documentation, or add a whole section of documentation of a different type.

You can't expect someone not core to a project to just propose to restructure the whole documentation. Which may also mean changing the website.

And in any case, such overhaul coming from a "nobody" would very likely be rejected as being both too large or incomplete or not desirable.

Re-structuring needs to be pushed for by at least one person from the core team.

So yeah "Just submit a PR" in that context is not an answer, it's an excuse to avoid trying to understand the problem and actually improve the situation.

A PR needs maintainer approval. And the maintainer I've seen thinks the documents are good enough already. In cases like that, a PR might not be able to solve the problem.

Complaining about it reroutes people to better projects, and pushes the project to fix the problem.