Re: Cataloging LDP White Paper: Document Reorganization

["David C. Merrill, Ph.D." <dcmerrill@mindspring.com>]

From: "Kevin Cullis" <kevincu@orci.com> Friday, October 13, 2000 3:29 PM


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

We've made the decision to merge HOWTOs and mini-HOWTOs, because the
separation is arbitrary. I don't know why the merge hasn't been performed on
the website, but I assume it's because the volunteers are really busy.

> 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 two issues involved in implementing any kind of standards on the
LDP.

First, getting new authors to follow the recommendations, which we can
probably do to some extent just by documenting the recommendations well. Our
LAG has improved so much in the last few months that, if you had seen the
HOWTO-HOWTO it replaced, you would be amazed. Yes, it can still be improved,
and I think we all appreciate your willingness to contribute.

Second, working with the existing documents. This is more problematic. The
majority of our documents do not even allow editing by anyone but the
original author, as I'm finding as I am reviewing our collection myself.

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

We currently have no documents that would fit in the CODETO category. We
have more general programming HOWTOs about specific libraries and
technologies and languages, but not about programming on a specific project.
I think documenting that really belongs with the software project itself,
not the LDP, especially since it changes so very quickly. I'm not really
interested in hosting the "how to get involved in developing foo 1.2 HOWTO".

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

I like your general approach, but would scrap the CODETO part and replace it
with an "Advanced Concepts" idea.

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

Backgrounders would be wonderful to encourage and support. Absolutely the
best part of your entire beta-proposal so far, IMHO.

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

All a very good idea, although there are some information domains where
*any* hierarchy you come up with will fail. You can't translate the
structure of a programming HOWTO to a configuring sendmail HOWTO to a
Linux-Advocacy HOWTO and expect it to work.

The whole concept of standardizing the layout of the HOWTOs works pretty
well when it comes to header and trailer information, but I think it falls
on its face for the internal structure. Not all the time, but often.

This doesn't mean I don't think it's a good idea to create one and suggest
people use it if it fits for them.

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

I already said what I think of this.

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

Except that CODETOs are NOT just "greater detail" of the HOWTOs. They are a
completely different subject area. Unless you mean them to be HOWTOs about
how to code for the application that the HOWTO covered. This, I think, is a
bad thing for us to be doing. It should be up to the project to document
their own developer process, usually on their web site.

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

It's not too much to bite off. You have some interesting ideas, and this is
an area I have also advocated working on, so I'm glad to see you doing this.

Regards,

--
David C. Merrill, Ph.D.
LDP Collection Editor & Coordinator
www.LinuxDoc.org



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