Date: Wed, 13 May 1998 16:02:40 -0700 From: Studded <Studded@dal.net> To: Sue Blake <sue@welearn.com.au> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: file://localhost/usr/share/doc/handbook/handbook.html Message-ID: <355A2690.92BFF443@dal.net> References: <19980513195232.16585@welearn.com.au> <Pine.GSO.3.96.980513163037.21600A-100000@james.hwcn.org> <19980514075238.04044@welearn.com.au>
next in thread | previous in thread | raw e-mail | index | archive | help
Sue Blake wrote:
>
> On Wed, May 13, 1998 at 04:37:37PM -0400, Tim Vanderhoek wrote:
> > You didn't check the "SEE ALSO" section to find-out what tput(1)
> > means by "attribute". :)
>
> Of course not! :-) There was absolutely nothing there to indicate that
> more information on the meaning of "attribute" was available, or needed.
Just about everything on the first screenful of the tput man page
indicates that it's related to the termcap database. Some examples:
NAME
tput - terminal capability interface
-T The terminal name as specified in the termcap database,
If the attribute is of type string, and takes arguments (e.g.
cursor
movement, the termcap ``cm'' sequence)
Also the fact that the word "attribute" is underlined indicates that
it's cross referenced somewhere else.
> >From past experience, "SEE ALSO" is there to list a lot of stuff that is
> even harder to understand than the current man page, and when it does
> contain information needed for the current task, that information does
> not leap out from the mass of techo-speak in the several long documents
> in "SEE ALSO".
Obviously you are speaking of your experience with the "see also" refs.
In fact what usually happens is that someone writing a man page for one
function references a related man page whose author has no idea that his
page is being referenced in that way. In this case the underlining of
attribute is a hint. Checking 'man 5 termcap' and searching for the word
attribute will help it "leap out" at you.
> The chances of finding, identifying, and working out how
> to use any necessary additional info are very small, and the cost
> (frustration) is high enough to convince a good learner that this is not
> an efficient way to learn.
You are making an unecessary value judgement with your use of the term
"good" in this context. The problem in this context (as we've discussed
before) is that there are different ways to learn and grasp concepts.
The problem with a lot of unix documentation (and especially man pages)
is that it's written by people who are extremely left-brain oriented and
therefore have a difficult time presenting information in a way that
helps non-techie's grasp the concepts.
> After looking at termcap(5) I would have had no idea that it was useful
> to me if someone hadn't already pointed that out. Now I guess that
> anything referred to as an attribute in termcap(5) could be used with
> tput, but I don't hold that belief with strong conviction and would never
> have gotten to this point without being told.
Your ability to intuit these connections improves over time as you gain
more experience putting the various pieces of the system together in a
way that suits your purposes.
> There must be a set of attitudes and behaviours that can improve just
> about anyone's use of man pages.
'man man' helps. So does writing a few manual pages of your own. :)
> I'm starting to think that the act of
> using man pages with neither guidance nor success can lead people away
> from these ideal attitudes and behaviours, rather than to them.
Success reinforces learning, failure reinforces avoidance. This is true
in any endeavor.
> Possible
> solutions would be alternative man pages for newbies that encourage their
> correct use and transferrability of skills,
Completely impossible and totally undesirable for a large variety of
reasons. It is much better to improve the ones we have so that the
information is more accessible to a wider variety of learning styles.
> or a carefully planned
> tutorial in the use of man pages the way they are, or both.
A tutorial would have a great deal of value in this area. I've got some
very rough notes for one myself, but realistically it's at least a month
before I could even consider this myself. Hopefully someone else could
get to it faster. :)
> I see this as
> a training design problem more than a straight documentation problem. One
> day I'll work out what to do about it :-)
That's another problem with this perspective. Manual pages are not
designed for training. They are designed to document features in a quick
reference manner. Many groups (including and especially GNU) are
abandoning man pages altogether or supplementing them with 'info' or
other types of detailed documentation.
The answer to this problem is very similar to the answer to the other
problems we have of this type. We need to improve the documentation we
have and work hard on making it more accessible to a wider audience.
Doug
--
*** Chief Operations Officer, DALnet IRC network ***
*** Proud designer and maintainer of the world's largest Internet
*** Relay Chat server with 5,328 simultaneous connections.
*** Try spider.dal.net on ports 6662-4 (Powered by FreeBSD)
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?355A2690.92BFF443>