From owner-freebsd-doc Wed May 13 14:52:59 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id OAA25236 for freebsd-doc-outgoing; Wed, 13 May 1998 14:52:59 -0700 (PDT) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from phoenix.welearn.com.au (suebla.lnk.telstra.net [139.130.44.81]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id OAA25224 for ; Wed, 13 May 1998 14:52:52 -0700 (PDT) (envelope-from sue@phoenix.welearn.com.au) Received: (from sue@localhost) by phoenix.welearn.com.au (8.8.5/8.8.5) id HAA06853; Thu, 14 May 1998 07:52:43 +1000 (EST) Message-ID: <19980514075238.04044@welearn.com.au> Date: Thu, 14 May 1998 07:52:38 +1000 From: Sue Blake To: Tim Vanderhoek Cc: freebsd-doc@FreeBSD.ORG Subject: Re: file://localhost/usr/share/doc/handbook/handbook.html References: <19980513195232.16585@welearn.com.au> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.88e In-Reply-To: ; from Tim Vanderhoek on Wed, May 13, 1998 at 04:37:37PM -0400 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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