Re: man/info debate

[Patrick Callahan <pac1@tiac.net>]

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.

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

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