Re: DocBook Walkthrough?

[pac1@tiac.net]

jdd wrote:

> On mar, 16 mai 2000, pac1@tiac.net à écrit
>
> I wonder if the documentation project could benefit
> >from
> >more active discussion of "What is it we're trying to do exactly?"
> >rather than
> >"What tools are we using (today, yesterday and tomorrow) and how do they
> >work?"
> >or "Which tool is best for what"
> >
> >
>
> I think we work on a particular basis. Most HOWTO authors use an immédiate
> experience to help others. This can barely be planned.

I think it can be   Plan the experiences, Plan what kind of information to
gather, and where possible, plan on specific pieces of information to gather.
Plan how the information about an experience is to be organized and used.   Do
we know how to do this today?  No, I don't think we do.  Should we learn how to
do this?  Would it result in better HOWTO's?

>
> The necessity effectively enphasised in your letter to have multiple
> formats obliges us to keep very straight to the minimal format (linuxdoc
> for example)

 I think today, we're at the level of creating "Documents" that can be presented
in a variety of presentation formats", but the content of the various formats is
fixed.  Is this correct?

Since we are beginning to separate content from presentation format in a very
formalized way,  I think the capability of customizing not just the format but
the content is already feasable.

The purpose of separating semantics from style and marking content semantically
is NOT just so you can present the content in a variety of media formats and
styles, but also so you can create formats and styles that OMIT some of the
content.  This allows making the presentation in a variety of formats suitable
for different audiences.  Not just n different output formats, but  m different
documents in each of the n different output formats, all from ONE source.


I'm not arguing against linuxdoc, docbook or any other current format.  I'm
arguing for a view of documentation, and software specifications that carefully
mark the content so that it can be used to produce documents with different
content and emphasis.   I'm arguing for an exploration of objects of type
"package", "command", "distribution", "program", "protocol" and their
documentation and programming interfaces to various kinds of people  all of whom
need documentation in various levels of detail, presentation style and content,
depending on their level of experience and the specific task they are faced
with.

There are  13 kinds of tasks I've found so far.

1. Installing a distribution
2. Obtaining generic linux user skills
3. Building a kernel
4. Hardware administration
5. User Administration and Security
6  Obtaining generic package building and installing skills
7. Choosing packages to build and install

For each chosen package:
8.   Building the package
9.   Installing the package
10 Administering and securing the package
11. Using the package
12. Creating and maintaining the programming envirionment
13. Creating, maintaining and using the programming environment for a specific
package


There are 6 levels of expertise related to things a Linux person may try to do.

1. Unaware of availability or alternatives
2. Initiate - Has made a choice but lacks knowlege of how to proceed to
implement the choice successfully
3.  Novice - Has Found the Fine Manual and read parts of it that seem relevant
and has not yet attempted to use it
4. Trainee - Has Read most of the Fine Manual, and tried it and succeeded at
least once.
5. Expert  - Has read and understood the Fine Manual, done it at least once and
could do it again the same way or with common variations without occasional use
of documentation
6. Master - knows it cold.  has little use for documentation because the Fine
manual and all other documentation is essentially reproduced in wetware)

For a given task, a person may fall into any one of these 6 expertise
categories, and for each level, a certain subset of the total available
documentation (TAD) is appropriate.


This is my central Point:

What I'd like to see, is a central data store for the Total Available
Documentation that can be used to produce the "appropriate" content for the
different levels of expertise and perhaps also for  different tasks.   The
CONTENT would vary, not just the presentation format.


jdd concluded:

> this is my own feeling, may be others think differently...

My hardware manufacturer advises just that "Think different!".   My other
hardware manufacturer simply advises "Think!".

-Pat




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