From: Bakul Shah <bakul@bitblocks.com>
To: Norman Wilson <norman@oclsc.org>
Cc: tuhs@tuhs.org
Subject: Re: [TUHS] earliest Unix roff
Date: Thu, 19 Sep 2019 13:53:19 -0700 [thread overview]
Message-ID: <7864DEA0-E980-4AAA-B5C0-059B6548C7DA@bitblocks.com> (raw)
In-Reply-To: <1568916649.17313.for-standards-violators@oclsc.org>
On Sep 19, 2019, at 11:10 AM, Norman Wilson <norman@oclsc.org> wrote:
>
> This pokes me in one of my longest-standing complaints:
>
> 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.
Agree 100%. But I think what we are really complaining about
is more recent program design & interface. Why do programs
have so many options. Why is their functionality partitioned
better.
next prev parent reply other threads:[~2019-09-19 20:51 UTC|newest]
Thread overview: 99+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-09-19 18:10 Norman Wilson
2019-09-19 18:37 ` Clem Cole
2019-09-19 18:44 ` Jon Steinhart
2019-09-19 19:44 ` Steffen Nurpmeso
2019-09-19 20:38 ` John P. Linderman
2019-09-20 13:41 ` Steffen Nurpmeso
2019-09-20 15:03 ` Steffen Nurpmeso
2019-09-19 20:53 ` Bakul Shah [this message]
-- strict thread matches above, loose matches on Subject: below --
2019-09-19 18:50 [TUHS] [OT] " Norman Wilson
2019-09-19 19:00 ` Nemo Nusquam
2019-09-19 20:18 ` Larry McVoy
2019-09-19 20:42 ` [TUHS] " Andy Kosela
2019-09-19 18:42 Norman Wilson
2019-09-19 22:42 ` Rob Pike
2019-09-19 22:55 ` Bakul Shah
2019-09-15 22:07 Doug McIlroy
2019-09-17 0:20 ` Steve Johnson
2019-09-17 1:11 ` Arthur Krewat
2019-09-17 1:17 ` Larry McVoy
2019-09-17 1:26 ` Clem cole
2019-09-17 1:33 ` Larry McVoy
2019-09-17 22:39 ` Dave Horsfall
2019-09-17 1:36 ` Richard Salz
2019-09-17 1:57 ` Bakul Shah
2019-09-17 1:19 ` Bakul Shah
2019-09-15 2:45 Doug McIlroy
2019-09-13 3:20 [TUHS] My EuroBSDcon talk (preview for commentary) Warner Losh
2019-09-13 19:47 ` Clem Cole
2019-09-13 20:02 ` Clem Cole
2019-09-13 20:06 ` Clem Cole
2019-09-13 20:24 ` Jon Steinhart
2019-09-13 20:43 ` Clem Cole
2019-09-13 20:53 ` Diomidis Spinellis
2019-09-13 21:45 ` Clem Cole
2019-09-13 22:13 ` [TUHS] earliest Unix roff Warren Toomey
2019-09-13 22:55 ` Clem Cole
2019-09-14 2:02 ` Larry McVoy
2019-09-14 2:44 ` Warren Toomey
2019-09-15 2:56 ` U'll Be King of the Stars
2019-09-15 6:54 ` arnold
2019-09-15 7:01 ` Dave Horsfall
2019-09-15 16:17 ` Jon Steinhart
2019-09-15 17:23 ` Ronald Natalie
2019-09-15 19:48 ` Clem Cole
2019-09-15 21:16 ` Dave Horsfall
2019-09-15 7:32 ` U'll Be King of the Stars
2019-09-15 7:46 ` arnold
2019-09-15 19:37 ` Clem Cole
2019-09-16 5:52 ` arnold
2019-09-16 12:10 ` Clem Cole
2019-09-16 12:26 ` Lars Brinkhoff
2019-09-16 13:42 ` Clem Cole
2019-09-16 14:54 ` Larry McVoy
2019-09-16 16:09 ` Paul Winalski
2019-09-16 22:05 ` Dave Horsfall
2019-09-16 22:33 ` reed
2019-09-17 0:11 ` Dave Horsfall
2019-09-17 0:02 ` Nemo Nusquam
2019-09-17 0:21 ` Arthur Krewat
2019-09-17 11:12 ` Thomas Paulsen
2019-09-17 0:46 ` Clem Cole
2019-09-16 13:13 ` Chet Ramey
2019-09-16 14:51 ` Larry McVoy
2019-09-16 14:57 ` Clem Cole
2019-09-16 15:14 ` Richard Salz
2019-09-16 15:48 ` Ronald Natalie
2019-09-16 16:10 ` Larry McVoy
2019-09-16 16:16 ` Jon Steinhart
2019-09-16 16:26 ` Larry McVoy
2019-09-16 16:31 ` Richard Salz
2019-09-16 16:45 ` Larry McVoy
2019-09-16 17:19 ` KatolaZ
2019-09-16 17:24 ` Larry McVoy
2019-09-16 17:32 ` Jon Steinhart
2019-09-16 17:35 ` Clem Cole
2019-09-16 17:37 ` Jon Steinhart
2019-09-16 18:04 ` Chet Ramey
2019-09-16 18:19 ` KatolaZ
2019-09-16 23:24 ` Dave Horsfall
2019-09-16 17:24 ` Clem Cole
2019-09-16 17:00 ` Clem Cole
2019-09-17 11:20 ` Thomas Paulsen
2019-09-16 19:13 ` Steffen Nurpmeso
2019-09-16 19:31 ` Bakul Shah
2019-09-16 22:35 ` Dave Horsfall
2019-09-17 7:53 ` arnold
2019-09-17 14:21 ` Clem Cole
2019-09-17 15:03 ` arnold
2019-09-17 15:58 ` Christopher Browne
2019-09-17 18:15 ` arnold
2019-09-17 18:32 ` Warner Losh
2019-09-18 0:42 ` Adam Thornton
2019-09-16 21:42 ` Dave Horsfall
2019-09-16 21:48 ` Larry McVoy
2019-09-16 21:54 ` Jon Steinhart
2019-09-16 21:59 ` Larry McVoy
2019-09-17 5:07 ` Lars Brinkhoff
2019-09-16 22:10 ` Bakul Shah
2019-09-17 0:16 ` Greg 'groggy' Lehey
2019-09-17 0:31 ` Jon Steinhart
2019-09-17 12:20 ` David
2019-10-05 19:44 ` Michael Parson
2019-09-15 19:35 ` Clem Cole
2019-09-15 20:49 ` U'll Be King of the Stars
2019-09-16 6:20 ` arnold
2019-09-16 12:13 ` Clem Cole
2019-09-16 12:34 ` arnold
2019-09-16 14:52 ` Larry McVoy
2019-09-15 19:27 ` Clem Cole
2019-09-15 19:31 ` Jon Steinhart
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7864DEA0-E980-4AAA-B5C0-059B6548C7DA@bitblocks.com \
--to=bakul@bitblocks.com \
--cc=norman@oclsc.org \
--cc=tuhs@tuhs.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).