Date: Thu, 14 May 1998 07:52:38 +1000 From: Sue Blake <sue@welearn.com.au> To: Tim Vanderhoek <hoek@hwcn.org> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: file://localhost/usr/share/doc/handbook/handbook.html Message-ID: <19980514075238.04044@welearn.com.au> In-Reply-To: <Pine.GSO.3.96.980513163037.21600A-100000@james.hwcn.org>; from Tim Vanderhoek on Wed, May 13, 1998 at 04:37:37PM -0400 References: <19980513195232.16585@welearn.com.au> <Pine.GSO.3.96.980513163037.21600A-100000@james.hwcn.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, May 13, 1998 at 04:37:37PM -0400, Tim Vanderhoek wrote:
> On Wed, 13 May 1998, Sue Blake wrote:
>
> > > Although, of course, the correct way to beep from an sh file is
> > > to use `tput bl`.
> >
> > Jeez, no matter what the subject, someone comes up with a command I've
> > never heard of :-) OK, it works great but how come the man page doesn't
> > mention it?
>
> 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.
>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". 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.
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.
There must be a set of attitudes and behaviours that can improve just
about anyone's use of man pages. 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. Possible
solutions would be alternative man pages for newbies that encourage their
correct use and transferrability of skills, or a carefully planned
tutorial in the use of man pages the way they are, or both. 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 :-)
--
Regards,
-*Sue*-
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?19980514075238.04044>