Most documentation is so bad and so often out-of-date that I can answer my question faster by reading the source (or tests).
Everything is so extremely verbose. I don't want to read a 7 paragraph essay about how this or that feature was developed and evolved over time; I just need a one line hint and maybe an example. Believe it or not, your software is not special. We've seen something like it before and get the gist already. I like the style of man pages, where everything is on one page and organized by the flag, i.e. actual usage (puts a hard limit on meandering bullshittery).
You are in the minority, mate. Man pages are walls of text that cover too much detail in too little space. A lot of them lack examples.
Most people will take a simple task-oriented tutorial over an all-encompassing man page. That’s something that Microsoft understood very well back in the ‘90s, providing copious amounts of examples and tutorial on top of basic reference material. It’s part of the reason they saw orders of magnitude more adoption for their stack.
> Most documentation is so bad and so often out-of-date that I can answer my question faster by reading the source
Especially within a company. Once place I worked, a few teams liked to over-document, though it wasn't enforced org-wide. The docs were usually not very helpful, outdated, and yes, I could just read the code faster. I wish they put more effort into better factored code and better names.
Keep documentation close to the source to increase the odds it gets updated. Prefer READMEs to Wikis, and use source comments to generate docs rather than word/google docs. Some doc tools even test examples for you!
It's not perfect, and good documentation is an art, but if you care about your software and your users you'll try to communicate clearly.
Everything is so extremely verbose. I don't want to read a 7 paragraph essay about how this or that feature was developed and evolved over time; I just need a one line hint and maybe an example. Believe it or not, your software is not special. We've seen something like it before and get the gist already. I like the style of man pages, where everything is on one page and organized by the flag, i.e. actual usage (puts a hard limit on meandering bullshittery).