From owner-freebsd-doc Wed May 13 16:03:04 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id QAA09153 for freebsd-doc-outgoing; Wed, 13 May 1998 16:03:04 -0700 (PDT) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from dt050n33.san.rr.com (@dt053nd2.san.rr.com [204.210.34.210]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id QAA09140 for ; Wed, 13 May 1998 16:02:58 -0700 (PDT) (envelope-from Studded@dal.net) Received: from dal.net (Studded@localhost [127.0.0.1]) by dt050n33.san.rr.com (8.8.8/8.8.8) with ESMTP id QAA19927; Wed, 13 May 1998 16:02:41 -0700 (PDT) (envelope-from Studded@dal.net) Message-ID: <355A2690.92BFF443@dal.net> Date: Wed, 13 May 1998 16:02:40 -0700 From: Studded Organization: Triborough Bridge & Tunnel Authority X-Mailer: Mozilla 4.05 [en] (X11; I; FreeBSD 2.2.6-STABLE-0507 i386) MIME-Version: 1.0 To: Sue Blake CC: freebsd-doc@FreeBSD.ORG Subject: Re: file://localhost/usr/share/doc/handbook/handbook.html References: <19980513195232.16585@welearn.com.au> <19980514075238.04044@welearn.com.au> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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