The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations.

Then comes a description, which is fine, and then a list of options in alphabetical order which is almost always the least useful ordering. Categorize the parameters. Juxtapose confusingly similar options.

And only then do we get any examples, if any. The examples should have come first, in the synopsis.

There's nothing inherently wrong with man pages, but nobody has to follow this tradition. Put real examples in your synopsis and manually sort your options; you'll have a man page that's 20x better than most.

man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addition to man pages.

Edit: the wording was angrier than it needed to be. A concrete example of a better documentation tool : https://kapeli.com/dash

A well written manual page requires no additional tutorials, for they will be included in the text’s corpus.

Writing good documentation for one’s software is almost more important than writing the software itself; don’t force the user to have to run around the internet; be comprehensive in the manual.

How are you supposed to write reference documentation without a section for describing the options which can be referred to by option name?

> The examples should have come first, in the synopsis.

Type with me: / E X A <return>. If anything, perhaps the first manual a man user should read is the manual for their default pager, usually LESS(1).

There are good and bad manpages, but I don't see how the format is truly deficient. Some very complex commands have separate sections for the most and least common options (or groups of related options, if there are subcommands or similar).

That is just a terrible idea. First, if what you're putting in the synopsis is not "a brief summary or general survey of something" then the section is misnamed or the content does not belong there. Examples don't belong there. Second, and more importantly, plenty of commands can do enough damage that people ought to read up on what they do before receiving an example. You're giving someone a false sense of confidence if you throw an example at them first thing. That's appropriate enough in some contexts, but not in official documentation for software tools.

> The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad.

The problems you go on to list have nothing to do with the structure, and everything to do with the content contained within that structure.

> No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial.

Since "documentation experts" write documentation this way, it's hard to imagine why you'd assert this.

That said, if you’re writing, reviewing, and editing documentation, the traditional structure is hierarchical and consistent—-which is good.

Even as a reference manual, man is bad though.

If I'm looking for option "-e" of the test command, why can't I do

    $ man test -e
     -e file       True if file exists (regardless of type).

I get this is an historical tool that only cares about displaying the output of nroff. We would need a new tool with more empathy ($ woman? )

https://gist.github.com/alphapapa/3cba3ff196147ad42bac#file-...

    $ man test -e

           STRING1 != STRING2
                  the strings are not equal

           INTEGER1 -eq INTEGER2
                  INTEGER1 is equal to INTEGER2

           INTEGER1 -ge INTEGER2
                  INTEGER1 is greater than or equal to INTEGER2
    --

           INTEGER1 -ne INTEGER2
                  INTEGER1 is not equal to INTEGER2

           FILE1 -ef FILE2
                  FILE1 and FILE2 have the same device and inode numbers

           FILE1 -nt FILE2
                  FILE1 is newer (modification date) than FILE2
    --

           -d FILE
                  FILE exists and is a directory

           -e FILE
                  FILE exists

           -f FILE
                  FILE exists and is a regular file

I've found javadocs enormously helpful when I was learning Java 20 years ago. But then again, I also like man pages and use them a lot.

If I'm looking for option "-e" of the test command, here's what I would do:

    $ man test

Of course, you could also just define a bash function for the functionality you're after like so:

    mano() {
        man "$1" | grep -A1 -- "$2"
    }

    $ mano test -e

You could always make your function more clever, e.g.:

    function mano() {
        man "$1" | grep -A1 -- "$2\\b"
    }

    function mano() {
        man "$1" | grep -A1 -- "$2  "
    }

m, a Unix shell utility to save cleaned-up man pages as text:

https://jugad2.blogspot.in/2017/03/m-unix-shell-utility-to-s...

This tiny script lets you generate man pages as cleaned-up text, saves them in a ~/man directory, and you can from then on, open them in your favorite text editor or even pager (less/more/pg/etc.) and view them. Created it out of real-life personal need some years ago, on a Unix system, but is still useful on Linux and other Unix-like systems today.

  man test | grep -- ‘ -e’

For example: https://uk.mathworks.com/help/symbolic/svd.html

I ALWAYS have to Google it, since the man page gave me nothing.

On a real UNIX like illumos and SmartOS, EXAMPLES are mandatory; I’ve no idea why people believe they may be optional, as they are one of the biggest reasons why someone would call up a manual page. It’s a manual.

[0] - https://en.wikipedia.org/wiki/Man_page#Layout

A far better answer to this would have been a project to (1) improve man page examples, and then (2) create a small alternative man page client that displays only the examples (or puts them up top).

Having said that I do see the need for what tldr is doing, even though I would have preferred it added to existing tools. More often than not I only find man pages useful after I have needed to look up something. They're usually OK for wholistic understanding, but often too dense and assuming of far too much contextual knowledge to be useful in the heat of battle.

Or if that seems like a lot of keystrokes, /EX<enter> will probably jump to what you want most of the time too.

   > man less

   /EX
   pattern not found

   /ex
   ends up somewhere in the middle of the text 
   on a word that contains ex

How about '/examples'? Maybe you should take some time to actually learn how 'man' works before you start bashing it online...

    $ cat ~/.bin/eg
    #!/bin/bash
    man $@ | awk '/^EXAMPLE/ { getline; while ($0 !~ /^[A-Z]+/) { print $0; getline; } }'

I'd be more specific: man vs tldr/bro is almost like an appliance's user manual vs service manual. The latter is super in depth but usually doesn't explain in an understandable way how to actually use the tool. While the former does that, but once you're stuck it offers no deeper explanation and you're lost.

> This TLDR tool definitely needs to exist, but in conjunction with man pages, not as a replacement.

tldr is _exactly_ that. We do not and will not aim to replace man pages. We have a hard limit of 8 examples at max for every command. Therefore, our scope is very limited and we try to mention the 8 most important and practical examples a beginner needs to know for a command.

If someone needs to go deeper, man pages are always there.