Re: DocBook Walkthrough?

[Stein Gjoen <sgjoen@mail.nyx.net>]

pac1@tiac.net wrote:
> 
> 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.

In my case the Multi Disk HOWTO started out as a 3 page tech note,
grew with some notes during implementation, became a mini-HOWTO and
is now a 90 page monster HOWTO. I had no idea it would turn out this
way and suspect my experience is not unique.

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

[snip]

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

The LinuxDoc and related tools allow for conditionals for generating
not only various output formats but also contents extraction formatting.
You will not be surprised to hear the documentation for these features
are amazingly obscure.

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

I tried to cover some of this in the big HOWTO Template I announced
recently. I did it using a reading plan but not conditionals. That
could be an idea though.

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

This probably requires some new tags very specific to LDP and while
I am all for it I know others are reluctant.


> There are  13 kinds of tasks I've found so far.
>[snip]

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

After my HOWTO expanded beyond 50 pages I was asked for a reading plan
which you can see an example of here:
	http://www.nyx.net/~sgjoen/disk-2.html#ss2.3

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

I agree. In fact I see the stub man pages as examples of this.

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

I suggest we recruit people to fix the tools for us so we can move on
and implement these features. The DocBook DTD and related tools seem
a bit unstable and big for my tastes, there is still a lot of life left
in the old tools.

Regards,
   Stein Gjoen


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