[TUHS] man-page style

[Jon Steinhart]

David writes:
> The problem, as we have all converged on, is that writing well is hard. Writing
> concise, targeted prose, is even harder. So we get bloat in man pages or the
> info system which is just (IMHO) more bloat because people don’t want to spend
> the time writing well.

I'm going to be a bit contrary here.  Yes, writing is hard, but not that hard.
Designing is what's harder.  I'm gonna make the claim that a lot of projects
today aren't designed.  They're implemented, and when someone gets something
that sort of works they write down a few notes about what was hard for them
(if we're lucky) and passes that off as documentation.  We're in an era in
which it is so easy to just try things that many don't bother which what I'd
call design.  No surprise that "documentation" from "undesigned" isn't good.