Re: man/info debate

[David Merrill <dcmerrill@mindspring.com>]

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.
> 
> Don't just look at format and content.
> 
> 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'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.

I am very interested in this topic. I don't think it really belongs
here, but I can't suggest a more approproiate forum.
 
> -Pat
> 
> Brain dump:
> 
> 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.

I think you achieve a more practical perspective when you approach the
problem from the pov of the user. What are the contexts in which a user
seeks information? Then it becomes a Mohammed vs. the Mountain problem.
Is it necessary to bring the information to the user rather than making
the user come to the information.

Ideally, the system actively "learns" the user as the user learns the
system. Think "Diamond Age" for a SF interpretation. It seems that
commercial products have not yet surmounted the technical difficulties
in actually implementing such a system, but the concept is intriguing.

> 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.

How, then, do you explain Microsoft Bob? ;->

I posted on the list a week or so ago about the Dewey project
(dewey.sourceforge.org, RTFWWW), which is building a document storage
and retrieval system. The system is to be a back end for help
functionality. You might be interested in getting involved in that
effort. Dewey is in initial design stage, with not even a prototype
built, and it needs volunteers of a programming bent.

-- 
David C. Merrill, Ph.D.
dcmerrill@mindspring.com


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org