Manual entries, as printed by man and once upon a time in
the Programmers' Manual Volume 1, should be concise references.
They are not a place for tutorials or long-winded descriptions
or even long lists of hundreds of options (let alone descriptions
of why the developer thinks this is the neatest thing since
sliced bread and what bread he had in his sandwiches that day).

For many programs, one or two pages of concise reference is
all the documentation that's needed; no one needs a ten-page
tutorial on how to use cat or rm or ls, for example.  But some
programs really do deserve a longer treatment, either a tutorial
or an extended reference with more detail or both.  Those belong
in separate documents, and are why the Programmers' Manual had
a second volume.

Nowadays people think nothing of writing 68-page-long manual
entries (real example from something I'm working with right now)
that are long, chatty lists of options or configuration-file
directives with tutorial information interspersed.  The result
makes the developer feel good--look at all the documentation
I've written!!--but it's useless for someone trying to figure
out how to write a configuration file for the first time, and
not so great even for someone trying to edit an existing one.

Even the Research system didn't always get this right; some
manual entries ran on and on and on when what was really
needed was a concise list of something and a longer accompanying
document.  (The Tenth Edition manual was much better about
that, mostly because of all the work Doug put in.  I doubt
there has ever been a better editor for technical text than
Doug.)  But it's far worse now in most systems, because
there's rarely any editor at all; the manuals are just an
accreted clump.

And that's a shame, though I have no suggestions on how
to fix it.