Re: Cataloging LDP White Paper: Document Reorganization

[Kevin Cullis <kevincu@orci.com>]

David Lawyer wrote:
> 
> 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.

Sure you like to be over critical, David!  While I'll respond to each of
your commments below, your bad attitude comes through loud and clear!
BTW, have you ever read anything concerning QA or continuous improvement
(Deming, Juran, Crosby, Humphrey, Hammer, or any UML stuff)?  Because
based on your comments below, you've made some errors in judgement
regarding processes, systems, and objectivity. What I researched and
wrote in about 2 days and sent to the LDP's mailing list was in response
to Sandy's comment about things which need to be improved in the LDP on
Wednesday.  As I expected, someone only saw the trees (process) and not
the forrest (system) and refuses look at both at the same time: that's a
MAJOR error on your part and most people I know!!  Fortuneately I'm not
a 16 year old who would easily go off in a hurumphf and not come back,
but others might, David!  While I will view all of your criticisms, I
will throw out those that don't conform to QA principles and the focus
on continuously improving the quality of Linux documentation.

Oh, BTW, you failed to read or ignored what I wrote.  I stated that this
was ONE section of a SYSTEM I was working on and that it wasn't FINISHED
and I was looking for comments, both positive and negative.  So, see
below for my POSITIVE AND NEGATIVE comments.

See this article for more background about software quality:
http://www2.linuxjournal.com/articles/currents/019.html

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

No problem here. I didn't spend much time on it and wasn't expecting
good things out of it.
> 
> > ---------------------
> > Linux Documentation System White Paper:
> > Document Reorganization

Notice is say SYSTEM here. A SYSTEM is only as good as it's weakest
link.

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

Agreed.

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

Title of my email: Cataloging LDP White Paper; subsection: Document
Reorganization.  David Merrill's first effort at cataloging HOWTOs is a
good first step in the right direction (BTW, good job David).  A system
would cover ALL documentation.  Yes, all topics in each document, at
least how I'm seeing it now.  David Merrill started a cataloging system,
you want to throw out HIS work?  Here's an error in judgement.

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

No, we don't need a team to do this, I would expect that once the system
is complete or near completion that the HOWTO maintainers would be the
primary determiner and others would be secondary with input. No
different than people making comments to maintainers about their subject
matter.

Yes, a more standardized outline is what I'm proposing.  Yes different
HOWTO need different outlines, that's what I'm exploring at the moment.
How many would we need?  If you had read my outline, you would have seen
the backgrounder proposal. Don't you think that some of the HOWTOs might
belong there?  When I first got into Linux, I heard about HOWTOs, but
some of them don't read like I see the definition of a HOWTO, how to do
something. That's why I proposed the Backgrounder to take their place.
Since that reduces and reclassifies some HOWTOs, now the question
becomes: of what's left, is another outline needed?

I agree that authors need the freedom, but does a library card catalog
and a book's Title, Title page (and the page where the ISBN number and
date of publication is placed, I've forgotten my 6th grade class on that
:-) ), Index, Preface, Forward, and Table of Contents limit an author? 
MAJOR error here! All I'm asking is that when a timeframe, level of
knowledge (basic to advanced), or 

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

My ignorance, and thanks for the information, I'll review it for
relevancy to what I'm trying to accomplish. I"m sure that I can help
with that as well.

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

Creating the system will help with process.  Getting an overview is
still better than no documentation at all.  Based on what you've said,
I'll have to rethink this issue.

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

Why not?  Maybe what I'm doing might help the process some.  Again, the
quicker someone finds an answer, the quicker they can get back to work.

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

Absolutely true! Fixing my problem is first and foremost in my mind. HOW
I fixed it and HOW to prevent the problem again comes next and will take
time to understand it.

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

Hopefully LDP can help, but I'm not expecting it to rule the house on
this one. Again, any improvement is better than no improvement.

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

I wansn't expecting this to be finished or complete, just some thoughts.
I was more concerned about the content and logic than pretty and
grammatically correct.  I'll clean that up later, if I had gotten it
"perfect," some would have found problems with the logic and flow. 
Again, First things first.
> 
> 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.

MAJOR error here!  You don't begin with the trees first, you begin with
the forrest.  If you had followed my outline of documents, Backgrounder,
HOWTO, and CODETO, then you would have seen the simple to complex flow
of information. If you had read the sections 2.5.1, 2, 3, and 4 your
would have seen a logical flow of what you've described. But I totally
agree with your flow of information in describing information. In fact.
sometimes it's beneficial, based on feedback, to repeat or reinforce
difficult concepts or ideas from many different angles.

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

I agree with your comments, but the first thing is determining what is
being covered in the title?  pppd is software, but it interacts with
hardware, etc., but it's still software. An ethernet cards and modems
are hardware and software and interact with both (cables and kernel),
but they are primarily hardware.  That's where we start!  You have to
start somewhere, start with classification first, then move from there.
You wounldn't start in the middle would you?

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

Great idea, where would you see it fitting?  Could it be a
Suggestion/Improvements area?  If you have a better idea, I'm willing to
listen, but I'll put some thought to it myself.

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

If you had read under HOWTOs directly (and also 2.1.1 through 2.1.3 and
after, you would have understood that's exactly what I was proposing. 
My rationale for having a RELATED area was having one location to
quickly find information via GREP or other means.  The idea is there, I
just haven't got to the point of thinking it all of the way through yet.

Read what I said:

> The concept about Related Issue follows this sort of path: I've read the backgrounder about Printing and have started the Printing HOWTO.  My printing is up and running but now I want to network my printer.  Both the Printing and Networking HOWTO will have a Related Issue identifier identifying each others HOWTO and appropriate section to focus on.  I'm not particular about how this is done, whether it's a parenthetical insertion (Related Issue: Networking HOWTO: etc.) in the appropriate section, or, a seperate sentence within the appropriate section: Related Issue: Networking HOWTO: etc.  In any case, a cross reference should be identified when appropriate.

I could expect that there might be numerous Related Issues which each
would be placed at the appropriate place in the HOWTO.

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

I'll check on ODE.  Explain your too narrow comment versus too broad! 
I'm working on both, cataloging and HOWTO reorganization.

> 
> 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, while your comments bring up legitimate issues, how they are
integrated into what I'm tackling is another issue altogether, but
that's what I'm doing and don't expect you to do that since you're
working on other things. I appreciate your bringing up issues, however,
your attitude of Not Invented Here (NIH) or "I've been down this road
before" comes out pretty clear and I'm disappointed in it and expected
more from you.  If document maintainers can't see the bigger picture,
then it's up to me and others who do to try and convince them of the
benefits. If they don't, then I'd ask for others to rewrite the HOWTOs
if they think that my proposal has legitimate merit. That's freedom,
right?  But first, I'd do what I'd ask them by doing my own HOWTO as an
example and that I "eat my own dogfood!"

I look forward to your criticisms.

Kevin
begin:vcard 
n:Cullis;Kevin
tel;home:720-489-9283
x-mozilla-html:FALSE
adr:;;8285 S Poplar Way #202;Englewood;CO;80112;USA
version:2.1
email;internet:kevincu@orci.com
x-mozilla-cpt:;0
fn:Kevin Cullis
end:vcard