On August 9, 1999 at 22:32, someone wrote:
Point taken on the variation, and I see the redundancy as somewhat of
a "you say toe-may-toe, I say tum-mah-ta" situation - perhaps a middle
ground would be to use a list of available resource variable names
hyperlinked to the table? So, just this:
<a href="../rcvars.html#A_ATTR"><strong><code>$A_ATTR$</code></strong></a>
The problem with this is that it "too much clicking", or better said,
"over abuse of hyperlinking" (I hate the work "click"). A person would
have to jump back and forth to see what each resource variable
represents. I find this much more annoying then the case of
redundancy. Note, some form a redundancy is common among (good)
reference manuals. When a reader is looking up something, it is bad
practice to have them jump around alot for related minor information
when it is more convienent to just repeat the data so the reader can
stay focused on the task at hand.
Knowing when to be redundant can be subjective.
You are the first to complain about it (to me) wrt the MHonArc docs.
BTW, updating the resource variable tables is automated, so I do
not have to edit a bunch a files when add/modify variables.
That makes the maintenance task easier for you, but the person just
starting with MHonArc is still faced with 2-3 times as much
Note, such redundancy is usually more work for the writer.
documentation as source code - not much of a problem for someone who can
at least skim the Perl source for a sense of what is going on, but still
something that can *feel* like a wall-o-manuals at first:
$ du lib doc lpr
And how many users are going to du files. That implies some level
of technical ability, where the size of the docs will have little
effect. Also, size can be subjective. For example, the resource
variables tables can be perceived as one "chunk" of data. Plus,
a printed manual vs an electronic manual can have different
perceived sizes. This is definitely true of the MHonArc documentation
since the bulk of the "mass" is down in all the resource reference
pages.
If I were to write for hard copy media, I would make different
layout decisions.
I don't mean to sound whine-y about the docs - they're pretty complete
and clear, and except for the resource variable repetition and the
"airy" (lots of white space) layout, they generally remind me of the old
Limitation of HTML. I'd like to see the resource pages tighter also,
but when I take out the rules, the page seems too cluttered, and
sections not cleaning delimited. Plus, some browsers render "tighter"
than others. For example, Lynx is tighter in its rendering of the
pages.
V7 Unix -man style - terse and to the point - but some of the aspects of
The resource pages are meant to be like this (I try to embelish when
appropriate). They are meant for reference use. Note, there are parts
of the documentation that do not follow the manpage format.
getting to know MHonArc felt somewhat voluminous to me - even the
command line help is a bit like trying to drink from firehose:
$ ~/mha/mhonarc -help | wc
158 1096 9189
$ ~/mha/mhonarc -help | egrep -e '-no' | wc
28 224 1758
Not much can done here. Moving the description above the options would
probably be better. Note, it is common practice for -help to list all
available options. It is more designed as a quick reference, and can
only be complete for minor programs.
BTW, have you done the same for other (Unix) programs? Look at GNU ls:
shell> ls --help | wc
60 454 3776
I at least try to call the user's pager so it does not scroll off
the screen.
When programs hit a certain size, the command-line help message
becomes less applicable. Look at Xv for example. Decent documentation,
but -help message very terse.
What would you prefer as a -help message?
Anyway, I'm sure you've given these aspects thought over the years that
you've been creating and maintaining the programs, so I'll leave it at
that. Feel free to bounce (some of?) these comments off the mailing
list if you want, or not; with or without attribution as you prefer -
either way is fine with me.
Since you replied via private mail, I strip out address/indentity
if I cc the list in my reply (like in this message).
Note, I think such discussions are appropriate for the list since it is
about MHonArc, and I know there other users with their own ideas about
documentation. I am open to comments, but I cannot guarantee that I
will agree with all of them :-)
--ewh
P.S. I am the first to admit that the docs are not well suited for
users with less technical skills/knowledge. However, my main priority
of the docs is to document all the features. Then stuff like tutorials
are secondary. Sometimes it is more work to update the docs when a
code change is made then the work put into the code change.
Also, when I first developed MHonArc, the target user (like myself) was
expected to have some technical skills. I targeted admin types. I
never expected the diversity of the user base that has come about over
the years. Remember, MHonArc first started when Perl 4.036 was the
main stable release, and the users of Perl tended to be
admin/programmer types. It was not until Perl 5 came about, and
the easier installation of Perl on non-Unix systems (like Windows)
where Perl programs started getting more use by non-geek types.
