Re: man/info debate

[David Benfell <benfell@greybeard95a.com>]

Sorry I'm so far behind in my e-mail...

On Sun, Aug 27, 2000 at 01:36:56PM -0400, Patrick Callahan wrote:
> 
> Bruce Richardson wrote:
> 
> > Not that I'd shed a tear if the info tool disappeared.  I find it's
> > navigation method clunky and much of the GNU info documentation
> > appallingly written.
> 
My real complaint about info is that, especially for a newbie, it is
one more thing to learn.  The awareness I feel is required here is
that, very often the problems one encounters under Linux do not
involve simple, one-step solutions.  A new user can feel overwhelmed
as one thing leads to another and he has to learn it all.

Adding info as one more thing to learn is not helping.

> Don't just look at format and content.
> 
As long as you can extract the information you need, for the most
part, format isn't that big an issue.  But there are things that can
be done to make life easier.  To the extent that documentation is
formatted consistently, it helps people to extract the information
they're looking for.

When I speak of format, I mean not only the technical means of
presentation, be it man pages, HTML, etc., but the presentation of
content.  Remember text books -- yes, some of them were horrible, but
they incorporated some good ideas on the presentation of material.

It goes without saying that content needs to be accurate and decently
written.

> The problem to solve with documentation of any kind is to get the
> necessary correct, complete and relevant information to the right
> audience at the right time.  
> 
> If there's anyone who has actually studied tecnical documentation and
> its use as a process, I'd like to contact you. 
> 
> I'm looking for information on the basics of how relevant technical
> information can be communicated. I don't want to limit my thinking to
> specific implementations of mechanisms for information delivery such as
> man or info pages.  I'm not interested in disussing relative merits or
> quality of man pages, info-pages, html renderings of man pages,
> gnu-help, windows help, docbook, linux-doc, XML, HTML, handwritten notes
> or any other specific implementation of "documentation" although any of
> these could show up as examples in any discussion.  Instead, I'd like
> learn more about the communication processes used when we create,
> maintain, disseminate and use sofware.

I don't know how much help I can provide here, but I think you're at a
valid starting point.  Once you have the material, I presume you can
pretty much automate the process of producing whatever technical
format you'd like to deliver it with.

I object to info, but some love it.  My argument would be, get the
content.  Then convert it into whatever formats are practical.
There's no reason this has to be one format in a "my way or no way"
attitude.

> I'll meet with anyone on this issue in any appropriate forum if this is
> not the right one.  If discussion of this kind of abstract topic in this
> forum is not appropriate, you can e-mail me directly.
> 
> -Pat
> 
> Brain dump:
> 
If I may add a concept to what you state below, in general, available
documentation needs to do a much better job of covering the
contingencies where something goes wrong.  Look at the failure points
and stop assuming that they'll be obvious to anyone who follows this
path.

Consider error messages; they are the only clue a user often has that
something isn't going right.  And they are rarely informative.  They
often do not help a user to understand what is wrong or how to go
about fixing it.

Obviously we cannot anticipate every error condition.  But we should
structure documentation so it accommodates explanations of error
conditions and fill in the gaps as we go along.
> 
> Consider a point of information say the existence of a particular flag
> on a particular command.
> 
> Why is the point of information needed?
> What is its informational context of the point? 
> What patterns of information content are inherent in the information
> context?
> In what usage contexts is the point of information needed?
> How complex is the informational context?
> What are the classes of users?
> How well do users in the various classes understand the context of the
> information?
> What context information is necessary to provide comprehensible input to
> users in different classes?
> How is navigation affected by complexity of the informational context?
> What kinds of navigational schemes are relevant in various usage
> contexts?
> What kinds of navigational schemes are relevant in various informational
> contexts?
> How are points of information stored and organized.
> 
> At this point, discussions of man-page vs info page vs html rendering of
> man-page or info page just don't thrill me like they used to.  Making
> "better" man pages or "info" pages is not going to get us anywhere.  I
> think we need to think not about documents, but about information,
> contexts, structure, and usage.  Think globally.  Don't restrict your
> thinking to "commands" or "packages", dont restrict thinking simply to
> "user" documentation. 
> 
> Think about the need for information, its contexts, structure and usage
> in construction and maintenance of
> 
> - a product 
> - a product's construction documentation
> - promotional materials
> - administration documentation
> - user documentation
> 
> I'm not proposing any answers to these questions, I'm not proposing that
> we drop what we're doing and start over, I'm proposing that we start to
> think about these things and discuss them because our competition
> already does.  I think its probably one of the most important things
> they've gotten good at.
> 
> -Pat
> 
> 
> --  
> To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
> 
> 

-- 
David Benfell
benfell@greybeard95a.com
ICQ 59438240 [e-mail first for access]
---
There are no physicists in the hottest parts of hell, because the
existence of a "hottest part" implies a temperature difference, and
any marginally competent physicist would immediately use this to
run a heat engine and make some other part of hell comfortably cool.
This is obviously impossible.
                                -- Richard Davisson
 
					[from fortune]

PGP signature