Cataloging LDP White Paper: Document Reorganization

[Kevin Cullis <kevincu@orci.com>]

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

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

First things first.  Designing a cataloging system requires an
understanding of the content of the Linux documentation.  Once that is
understood, then the relationships of the information will bring out the
associated categorization for the catalog.

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.  Each of these areas satisfy some certain
conditions, but lack a cohesive approach to finding answers.  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.

As you can see from the flow of the information below, it moves from the
simple to the complex and can be used somewhat as a troubleshooting
checklist (it will also help prevent problems from occurring if things
are followed correctly).  This flow allows someone to move forward or
backward, depending on the circumstances from where they are and to see
where they might have missed something.  I would also expect that this
will help in two ways.  First, it will help people to think logically,
those writing the HOWTOs and those reading them and second, it will help
in cross-referencing and/or alignment with other HOWTOs in sharing or
linking important and related information.

The flow also provides a proposed reading list so that each progression
of reading leads to the next subject matter.  For example, by reading
the Backgrounder, then the HOWTO, then the CODETO (the developers
HOWTO), you'll, hopefully, become an expert developer in that area. 
However, as a user, I won't need to read the CODETO unless I want to
program or contribute to that subject.  On the other hand, as a
developer, I should be required to read the Backgrounders and HOWTOs to
understand what I'm working on.

I propose that there should be these types of documents and the expected
format of each.  Backgrounders, HOWTOs, and CODETOs.  Here is their
description:

1 Basics or Backgrounder:  This document will provide basic or
background information about a certain subject.  While not a "dummies"
book or paper, it provides some background of how things work from a
high level so that the subject matter can be understood when beginning a
HOWTO.  The expectation is that it covers the subject matter in key
concepts about the length of a paragraph or longer, depending on the
subject matter.  It can also be a more detailed description of basic
Linux subjects and could be pages long and would cover things such as
basic operations or multiple items in the subject matter.  The idea is
that it is primarily a description of a Linux subject matter with
technical terms and concepts, but it leaves the rest of the information
to the HOWTO such as installation and configuration. The
Basic/Backgrounder sets the stage for performing the HOWTOs. I would
also expect that if a Backgrounder is too big, that it would be split
into smaller sections.  For example: Backgrounder: Modem: Introduction;
Backgrounder: Modem: Operations; Backgrounder: Modem: Internal modem. 
Again, the flow should be from the simple to the complex, from start to
finish: First things first!
1.1  Key Concepts
1.2  Key Terms and definitions
1.3  Processes
1.4  Operations
1.5  Pros and Cons
1.6  Etcs.
* FAQs: Frequently Asked Question which are asked by people would
normally be here, but I propose that FAQs be included into the HOWTO in
their respective sections to keep with the flow of the logic.  It would
be outlined as: FAQ #1, or FAQ #2 and ANS #1 or ANS #2.  Or, you can
duplicate the FAQ within the HOWTO where it is appropriate in the flow
of things.

2  HOWTOs: Instructional document which does just that: tells a person
HOWTO do something.  If a person doesn't understand it, they should read
the Backgrounders to get the theory or key concepts of what's
happening.  In addition, in each section a Related Issue will be
included when needed.  A Related Issue: is a cross referencing
identifier which will facilitate searches for workarounds, problems,
etc.; identifies other areas of concern or decision making; will be
cross-referenced in related HOWTOs in an appropriate section; will be
placed in the logical position within the HOWTO; should follow the below
format examples:
2.1.1  Related Issue: Networking HOWTO: Setup Requirements: Yada Yada
Yada.
2.1.2  Related Issue: lpq Man Page Yaya Yada Yada
2.1.3  Related Issue: RPM HOWTO: Workarounds: SuSe Yada Yada Yada.
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.
2.2  Contact/Header info: Maintainer's name and address(es), version
number, Date, etc.
2.3  Pre-dependencies: This should cover other HOWTOs or Backgrounders
which might be read or understood before proceeding further in the
current HOWTO.
2.4  Introduction Summary (Basics if short enough, i.e. a paragraph) 
Gives brief answers to the questions Who, What, Why, Where, When, and
How about the subject matter.  It gives the reader a summary of what
they are about to read or embark on and if it's over their head, to go
to the Backgrounder to get acquainted with the subject.  It also give
the reader an idea of what it is if they've never encountered this
subject before, a sort of encouragement to read or do more.
2.5  Body: The body will cover the following subject matter in the
following order: hardware, hardware and software, software, and then
????  The flow of information will be patterned after the OSI model with
the physical connections starting first and then moving into the
software installation and configuration, a "First things first"
approach.  You can't load Linux software unless you have a computer to
put it in ;-).
2.5.1  Setup Requirements: Covers everything you need to finish the
HOWTO (such as hardware/software).  This would also include a section in
which a decision would need to be made, such as which modem do you want
to use, ISA, WinModem, or PCI?  It would be cross referenced with the
pros and cons section of the Backgrounder.
2.5.1.1  Download files: location.
2.5.1.2  Necessary files, libraries, version numbers, etc.
2.5.1.3  ????
2.5.2  Installation/Configuration: Step by step set of instructions
which will get things up and running.  It will include: related
files/directories, etc.  
2.5.2.1  Uncompress files.  Here, there would be a cross reference to
the Compression HOWTO for more details.
2.5.2.2  Make, make install, RPM, etc.  Again, cross referenced.  
2.5.2.3  Setup/Configure.  Which files/directories/etc. should be
referred to.
2.5.3  Intermediate: Taking the HOWTO to the next level so that a person
can get more out of what the hardware/software does as well as custom
configuration or "personalization."
2.5.4  Advanced:  Tuning and advanced techniques for getting the most
out the HOWTO.
2.5.5  Upgrade Process.
2.6  Troubleshooting: This section should be "outside" of the above
information, i.e. If I follow the HOWTO exactly, then I should be up and
running.  If not, that's why there is this section, for those situations
which are not eliminated by the above procedures.  This section should
be a "checklist" that will logically eliminate problems to their source
after following the installation procedures.  It should also include
covering setup and configuration as well as known problems with specific
hardware/software and encourage the reader to move to the Workaround
section.
2.7  Workarounds:  This should be know problems that have been solved
but that haven't been included in current distributions, etc.
2.7.1  Tips and Tricks to getting things to work.
2.8  Related HOWTOs:  This section would identify other HOWTOs which the
reader might consider for more information or related subjects.  Ex. The
Printing HOWTO would have a section concerning printing on a network, so
the Networking HOWTO would be identified here.  In the Networking HOWTO,
in this section would be the Printing HOWTO.  Example: Networking HOWTO,
TCP/IP HOWTO, etc.
2.9  Related Man Pages:  This would assist others in identifying Man
pages which would be related to the HOWTO.  Example: lpq, lpr, etc.
2.10  Related Files: This section would be cover related files that
either affect the HOWTO or could cause issues with this HOWTO.
2.11  Post-dependencies:  This should be other HOWTO suggestions such as
developer CODETOs and such which the reader might consider for
furthering their Linux experience.  Example: Ghostscript HOWTO after
reading Printing HOWTO.
2.12  Appendix A (Administrivia and such.  Most people could care less
about this section, so that's why it's here.  Learning Linux or solving
their problems is what users want) in no particular order for now:
2.12.1  License
2.12.2  Feedback
2.12.3  Copyright Information
2.12.4  Standard Disclaimer
2.12.5  Acknowledgements
2.12.6  Other Sources of Information
2.12.7  Version History
2.13  Appendix B, C, D, etc: As needed by each HOWTO maintainer.

3   CODETOs:  Developer CODETOs are modeled after the HOWTOs in format
only, but the body could change depending on the content.  Developer
CODETOs would assist developers in planning, coding, and testing of
hardware/software.  As a Linux user, I may not want to know about
programming and therefore don't want to see developer HOWTOs (or
proposed CODETOs).  Currently, as a user it wastes my time and effort to
find those that I'm ONLY interested in when user and developer HOWTOs
are intermingled.  However, a developer might be interested in the user
HOWTO as they develop solutions for Linux users.  While I've copied the
HOWTO format, I'm not a programmer and therefore would allow someone
who's a programmer take this on.  My hope is that the principle and
logic flow would remain similar to keep consistent with the proposed
HOWTO new format.
3.1  Contact info: Maintainer's address(es), Version number, Date, 
3.2  Pre-dependencies: This should cover other HOWTOs or Backgrounders
which might be read or understood before proceeding further in the
current HOWTO.  Example: 
3.3  Introduction Summary (Basics if short enough, i.e. a paragraph) 
Answers the questions: Who, What, Why, Where, When, and How about the
subject matter, i.e. In an overview, details will follow in the body
section.
3.4  Body: 
3.4.1  Setup Requirements: Covers everything you need to finish the
HOWTO, such as hardware/software).  This would also include a section in
which a decision would need to be made, such as which modem do you want
to use, ISA, WinModem, or PCI? It would also cover the pros and cons of
each to give the user different perspectives.
3.4.2  Installation/Configuration: Step by step set of instructions
which will get things up and running.
3.4.3  Intermediate: Taking the HOWTO to the next level so that a person
can get more out of what the hardware/software does as well as custom
configuration or "personalization."
3.4.4  Advanced:  Tuning and advanced techniques for getting the most
out the HOWTO.
3.4.5  Troubleshooting: Should be a "checklist" that will logically
eliminate problems to their source.  It should also include covering
setup and configuration as well as known problems with specific
hardware/software and encourage the reader to move to the Workaround
section.
3.5  Workarounds:  This should be know problems that have been solved
but that haven't been included in current distributions. Etc.
3.5.1  Tips and Tricks
3.6  Related HOWTOs. This section would identify other HOWTOs which the
reader might consider for more information or related subjects.
3.7  Post-dependencies:  This should be other HOWTO suggestions such as
developer HOWTOs and such which the reader might consider.
3.8  Appendix A (Administrivia and such.  Most people could care less
about this section, so that's why it's hear.  Learning Linux or solving
their problems is what users want):
3.8.1  License
3.8.2  Feedback
3.8.3  Copyright Information
3.8.4  Standard Disclaimer
3.8.5  Acknowledgements
3.8.6  Other Sources of Information
3.9  Appendix B, C, D, etc: As needed by each HOWTO maintainer.
------------------------

As you can see by the process of this, it starts with a high level
overview and moves into greater and greater detail as you move down
through the documentation.  I would expect that the format would not
change once agree upon, but sections which do not need to document
information would say Not Applicable or N/A.
I also think that the LDP should provide a framework of HOWTOs which are
left blank to show others that there is a need for it.  For example,
rather than wait for someone to propose a HOWTO, begin listing holes in
the HOWTOs which need to be filled.  By outlining a "comlete" list of
HOWTOs and whether they're in listed only, in work, done, or being
updated, at least it might spark some interest.

I hope this isn't too much to bite off, but I believe in making things
easier and it's my hope that this outline will help in this endeavor. I
look forward to hearing from each of you and your comments.  This is
only one in a number of proposals that I will be making in the next few
weeks.

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