Re: Cataloging LDP

[Kevin Cullis <kevincu@orci.com>]

Stein Gjoen wrote:
> 
> Kevin Cullis wrote:
> [snip]
> > 1  Process
> > 1.1  Linux Development
> > 1.1.1  Theory/Philosophy
> > 1.1.2  Planning: Architect Design/Requirements Gathering
> > 1.1.3  Coding
> > 1.1.4  Compiling
> > 1.1.5  Testing
> > 1.1.6  Release/Acceptance
> > 1.1.7  Maintenance
> > 1.2  Linux User and Administration
> > 1.2.1  Background Information
> > 1.2.2  Pre-installation requirements (chipset or specifications of
> > hardware, etc.)
> > 1.2.3  Installation
> > 1.2.4  Configuration
> > 1.2.5  Maintenance/Tune-up
> > 1.2.6  Troubleshooting
> > 1.2.6.1  Pre- and Post-Dependencies of subject matter ( what items
> > affect it working correctly)
> > 1.2.6.2  Where to go for more info (i.e. to manufacturer for specs)
> 
> Funny, this list is not entirely unlike the structure in the
> Template
>         http://www.nyx.net/~sgjoen/template.html
> 
> > The one question I have not figured out yet, is how to do a
> > Beginner/Intermediate/Advanced sort of subject matter.  Should we
> > reclassify some things to basics/intermediate/advanced?  Let me know.
> 
> The way I see it a HOWTO should cater for the entire range of
> readers, hopefully bringing the novice up to speed. I added a
> reading plan to my HOWTO,and also the template (chapter 2.3) on
> request from a reader.

Not only a range of readers, but a range of HOWTOs, by that I mean some
HOWTOs are not really HOWTOs but general reading stuff or background
stuff which leaves me with a "What's this" sort of thing.  I'm not
knocking them, but the classification of information within the HOWTOs
makes it difficult to find the right information quickly.

> 
> How does this scheme fit in with your views?

We're thinking along the same lines with what you've started, however,
let's back up a bit.  While you've written (or are writing) a HOWTO for
big HOWTOs, the question has to be asked: why are there big HOWTOs? If
you take a survey of the HOWTOs, mini-HOWTOs, etc. and see WHAT type of
information is in each you find that all of them have similar
information, but when you look at the title HOWTO or mini-HOWTO via the
length or subject matter, then nothing is very consistent, at least
that's what I'm seeing.  So if what I'm seeing is accurate
(inconsistency between docs, such as a mini-HOWTO needing to become a
HOWTO, etc), then what of the first time user, or for that matter the
business manager who's looking at Linux, what do they think?  That's why
I'm taking the next two months off to do, to propose cleaning up the
inconsistencies to make it easier to find answers by creating a
cataloging system as well as creating definitions and logical flow of
what each document should contain..  My hope is that everyone will like
what I propose, but I would expect that it will require rewrites and
reorganizations of Linux docs. But then the benefit will be much cleaner
and focused docs.

Does this help?  I should have a rough draft in the next two weeks since
this entails a cataloging system, reorganizing the logical flow of docs,
and adding some features to which it will make finding answers easier.

> 
> Regards,
>    Stein Gjoen
> 
> --
> To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
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