In my experience, having to explain a software's design in plain English often reveals that some aspects were poorly thought-out in the first place.

...which in turn triggers defensiveness in some people, making a bad situation worse.

A lot of the time the language in man pages fine, but it could be easily clarified for first-time readers with simple examples. What is it with that? It seems to be an unwritten rule that Man Pages Shalt Not Provide Examples. Is there a good reason for this is or is it a "secret club"-type thing or something else?

EDIT: I "let me google that for you"'d myself and found this [0] right away which explains it, I guess.

[0] https://unix.stackexchange.com/questions/306189/why-dont-man...

The trouble with a lot of technical documentation, particularly man-pages and in-tool command-line help, is that it usually seems written as a reference/reminder for people who know more-or-less what they are doing already. You can often work things out from a more standing start, but that sort of documentation isn't optimised for this so you have to work for your illucidation.

For popular technologies there are often books, tutorials and other introductory articles. Git certainly has enough information to start out without reading every manpage.

I think this is why `tldr` is so helpful as a starting point: It's crowdsourced from other people than the dev who need to just get things done.

The single biggest contribution StackOverflow made to documentation as a whole was to flip the script.

Instead of the original developer of the material trying to prognosticate what questions people would have, people asked questions and either other users or the developer could answer them.

As this might not be obvious to all, tldr is a crowdsourced man-page replacement, and also really useful when working with git.

    $ tldr git cherry-pick
    
    Apply the changes introduced by existing commits to the current branch.
    To apply changes to another branch, first use `git checkout` to switch to the desired branch.
    More information: <https://git-scm.com/docs/git-cherry-pick>.
    
    - Apply a commit to the current branch:
        git cherry-pick commit
    
    - Apply a range of commits to the current branch (see also `git rebase --onto`):
        git cherry-pick start_commit~..end_commit
    
    - Apply multiple (non-sequential) commits to the current branch:
        git cherry-pick commit_1 commit_2
    
    - Add the changes of a commit to the working directory, without creating a commit:
        git cherry-pick -n commit

Believe it or not, I enjoy writing documentation.

I imagine it as a competition between myself and an adversary with an uncooperative attitude, one who's prepared to act smarter, dumber, better informed and more ignorant than I am in order to to find gaps, inaccuracies, or ambiguities in the docs I write.

It doesn't hurt that it improves my understanding of whatever it is that I'm documenting -- and where it could be improved.

This. I also like writing, but I love your description of technical writing as a (sort of) competition. Thanks!

I write docs with my most terrifyingly dangerous adversary in mind: Future Me. His forgetfulness and capacity for ignorant destruction are unparalleled, at least that's what Past Me says.

In the '80s, all we had on UNIX were man pages, and I was able to glean useful info from them.

Now they make my eyes glaze over, probably because every command now has 57 options. I just google how to do the thing.

There have never been "just man pages" in Unix. E.g. V7 had a number of papers (in troff format which could be rendered to the terminal or sent to the printer in finite time) that helped with understanding how to use the system (assuming you had more than the bare minimum disk space on your machine).

Yes, and I bought some of those at the campus bookstore. What I meant was that if you want to know how to do a recursive grep or something, man was the main resource. There was no google or stack overflow.

I basically never read man pages. In the overwhelming majority of cases you spend 20+ minutes reading the manual and it ends up not answering your question (or at least this is my experience) so you end up just doing a web search anyway.

Same here. I feel like a majority of documentation and eapecially man pages are helpfull if you already know it, but just need a reminder.

That hasn't been my experience at all, I find man and info pages hugely helpful.

A lot of documentation is atrocious, particularly for newer stuff. But I kind of disagree on man pages. At least, when I first encountered Unix, it was on old SunOS machines, and I remember being impressed first that everything was documented, and second, that the documentation was comprehensive and useful.

The things that make me most frustrated are when docs are missing, incomplete, or useless ("--foo: enables the foo option"). When it comes to man pages, at least in the good old days, I felt like I could always rely on them to cover all of the possible inputs, outputs, and errors, and to describe them, if not in the plainest language, in a way I could understand without being the author of the program.

For example, I don't have much bad to say about https://shrubbery.net/solaris9ab/SUNWaman/hman1/ls.1.html