Re: Cataloging LDP White Paper: Document Reorganization

[David Lawyer <dave@lafn.org>]

On Fri, Oct 13, 2000 at 01:29:51PM -0600, Kevin Cullis wrote:
> Hi all,
> 
> This is a draft of one section of what I'm working on.  I thought about
> waiting till this was "finished," but then you all might have additional
> ideas which I might not have thought of or considered.  Besides, maybe
> this will give you something to chew on while I continue to work on
> this.  So, chew away.
> 
> Kevin Cullis
> Denver, CO
> 720-489-9283
> 

I don't like to be over critical, but I think that what I read here
was almost a complete waste of time and a distraction from getting on
with the other tasks of updating my howtos, commenting on the
proposed manifesto, attempting to make it easy for new authors to
get started, and licensing issues.

First of all the introduction is poor.  It isn't clear what is going
to be proposed and it's not clear what the author is talking about
until one gets well into the white paper.	


> ---------------------
> Linux Documentation System White Paper:
> Document Reorganization
> 
> 10/13/00
> 
> Linux Documentation Project Vision:  To document the Linux Operating
> System
> 
> Linux Documentation Project Mission:  To document Linux solutions and to
> help solve problems.

Also, some howtos explain how hardware and software works so that
users will understand what's going on.  This is useful in
troubleshooting and non-standard configurations.

> 
> First things first.  Designing a cataloging system requires an
> understanding of the content of the Linux documentation.  

Out of the blue a "cataloging system" is mentioned.  What is this?  Is
it cataloging LDP's documents or all documents?  Is it cataloging the
various topics covered by each document?  Do we need a cataloging
system?

> Once that is understood, then the relationships of the information
> will bring out the associated categorization for the catalog.

What I think you mean is that we need to understand the content of our
docs so that we may catalog them.  Thus we need a new team to read
over all the docs to understand their content.  But what's proposed
here is a standard outline for howtos.  Would following the
outline enable us to understand the content better?   Perhaps but
HOWTOs on different topics need different outlines.  In fact I think
each needs it's own unique outline.  Also, the author needs a sense of
freedom to organized the material in the way s/he thinks best.

> Currently there are about five areas in Linux documentation which
> provide answers to Linux questions.  They are: HOWTOs, mini-HOWTOs,
> Guides, FAQs, and man pages.  

and GNU info docs plus the many thousands of docs in /usr/doc
and /usr/share/doc.  One "simple" application, kbackup, has about 200
different files containing documentation.  There was a group which
started looking into the problem of integrating the documentation but
they never finished the task.  I think they got partially sidetracked
discussing sgml formats such as DocBook.

> Each of these areas satisfy some certain conditions, but lack a
> cohesive approach to finding answers.

There isn't any cohesive approach to finding answers.  Understanding
the basic concepts may help but it isn't necessarily required.
Sometimes the default configuration works fine and one may be ignorant
of most all basic concepts regarding configuration.  Of course, you're
limiting the options you have if you're ignorant of configuration
options.  But for some, if the default works then that's good enough.

> I would suggest that HOWTOs and other documentation be split into
> three sections, as you'll see below (exception: man pages, but will
> be cross referenced in Linux documentation).  This reorganization of
> the document format is not intended to be limiting to HOWTO or
> document maintainer's, but to provide a consistent format which
> everyone can follow and quickly get to the necessary answers to
> their problem.  It will also help reduce redundancy throughout the
> HOWTOs, especially in the HTML versions, because of
> cross-referencing of information.  In addition, by organizing HOWTOs
> better, there should be a cascading affect amongst the distributions
> who may follow LDP's lead and contribute their HOWTOs to LDP,
> especially if we include a section or appropriate place for their
> comments in the HOWTOs about their distribution.

There are about 100 different distributions and most HOWTO authors
only use one (and don't know much about the others).  What's needed
here is more standardization of configuration across the various
distributions.  

> As you can see from the flow of the information below,

What information?  The information you are writing or the info in the
docs?  Below isn't just below but a few paragraphs below.  Of course I
now know what you meant now that I've read your white paper.  But a
first time reader has no idea of what you are talking about.

Now I'll digress on various topics.  There are many different ways to
explain something.  One method I tried is to first explain something
very simply and to make it so simple that some of the statements are
not exactly correct.  Then once readers get the idea, they read
another explanation of the same thing only in more detail and more
accurately.  One can even have a third repeat in still more detail.
This type of a document doesn't fit into your outline.

Many HOWTOs don't cover hardware at all.  But for covering hardware,
one needs to cover both hardware and the software controlling it in
the same explanation.  One doesn't always put one ahead of the 
other.  Hardware sends an interrupt that causes software to send a
voltage signal on a control wire, etc.  It's
hardware-software-hardware-software etc.

Part of a HOWTO might even be written to help someone design improved 
hardware as well as software.

You proposed having references to various sections of a related
documents all in one place.  Don't they belong at different places
depending on what's being discussed.  HTML links to sub-sections in
other docs stored on the same PC are needed in HOWTOs but how to do
this?  Does the other doc even have a label at the right location to
point to?

A suggestion is that you might want to check on what has gone on
before but was never completed.  They had their own list at
ode-discuss@oswg.org.  Is it archived?  ODE meant Open Documentation
Environment and was to include the BSD OSs.  So it's scope was broader
than LDP's.  In my opinion it was too broad but I think that your's is
too narrow and should consider docs that don't originate from the LDP.

Regarding your "CODETO".  There is a "Serial-Programming-HOWTO as well
as a "Serial-HOWTO" which I try to maintain.  The organization is
completely different and should be.  Now I'll go off-topic.  The
Programming one is obsolete and a new one has been written by a new
author.  But this author will not submit it due to our sgml formatting
requirements.  He says that even if we put it into DocBook for him, he
will not maintain it in this format (nor in LinuxDoc).  He had a
pretty bad experience with sgml.  I've about given up on trying to get
him to change his mind.

			David Lawyer


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