[SGVLUG] Documentation and the Linux Documentation Project

[David Lawyer]

On Fri, Jul 22, 2005 at 12:48:42PM -0700, A. J. Stasney wrote:
> I've done reasonably well at self-instruction on the command line in
> general, but despite two years of frustrating effort, reading
> endless and ultimately useless books, guides, manuals, etc.  I have
> NEVER succeeded in getting any  .tar.gz or similar file, whether
> binary or source code, installed and working.

This is one of the perhaps thousands of examples of shortcomings of
Linux documentation.  I've been involved some (but not enough, I'm
still supposedly on their staff) with the Linux Documentation Project
(LDP) which is supposed to provide documentation that is not otherwise
provided with software.  LDP has documented the use of various
hardware with Linux (but not enough and much is out-of-date).  Much of
the documentation is the interaction of hardware with software such as
the many HOWTOs on networks.

Another way to provide documentation is for Lugs and various others
(Linux mailing lists, personal websites) to provide help.  Then if one
has a problem, they Google to find the info on mailing lists, personal
websites, etc.  This is not an ideal way to provide help, but it's
better than nothing.  One problem: is the mailing list searchable by
Google and other search engines?  I don't think sgvlug's is.

Here are some other things wrong with the above approach to
documentation:  There is no review of what's written.  It may have a
lot of errors.  Also, it may be just how to solve a special situation,
while the documentation should be be written to cover a broader scope
of problems and perhaps to explain some of the "theory" behind what
one is doing.  Another shortcoming: duplication of effort.  Suppose
you explain something only to find that a better explanation exists on
the web.  There is so much documentation needed that doesn't exist,
that it is morally wrong to duplicate effort.  Yet there is a lot of
this duplication and sometimes it's beneficial, but not as beneficial
as it would be to put the effort into documentation which is sorely
needed but lacking.

This is why I'm not so sure that we need a tools section of the
website.  I suppose we do need it, but before someone writes
something, they need to check first to see if such documentation
already exists.  If it does, but needs improvement, they could first
suggest that the author update it.  If no success, then go ahead and
improve on it, making sure not to violate copyright law in doing so.
If the writeup is good, then they should submit a copy to the Linux
Documentation Project in a simple format like LinuxDoc.  I've written
a short tutorial on LinuxDoc and it's easy to learn.  LDP still
accepts this simple LinuxDoc format because I've argued for it, but the
standard at LDP is DocBook which is a lot harder to learn.  But they
will still accept LinuxDoc.

So what I'm doing here is asking for volunteers to help the LDP.  If
you author a HOWTO, you need to be willing to update it say about once
a year or so.  You also should deal with email from readers, who often
offer suggestions.  Others may email you for free help and you should
help them if they've made a reasonable effort themselves.  Sometimes
they've come across a problem that should be covered in the HOWTO.
But some requests for help need to be rejected, especially in cases
where the email is very poorly written or organized, or it's pretty
obvious that they didn't even bother to read (or search) your HOWTO
that contains the answer to their problem.  I also don't give help
regarding MS problems (Windows) where the requester may not realize
that the documentation is to help people with Linux and not with MS
Windows.

Volunteering will take time and LDP needs a lot more volunteers.  One
way to help is to just write a HOWTO, or rewrite one that is
out-of-date.  Another way would be to help get a CMS-database for LDP.
Someone said they would look into this but so far, no results.
Another way to volunteer is to review documents.  It's been my opinion
that LDP puts too many hurdles in the path of a new author such as
suggesting DocBook with little or no mention of LinuxDoc, requiring an
author to write a proposal (and encouraging an outline) before
starting to write, although LDP accepts docs already written so one
doesn't really have to do this.  You are also supposed to join the
mailing list which takes more effort to follow than sgvlug's list.  We
seem to lack any kind of a recruitment program for new authors, so I
guess we need recruiters (I'm making an minor attempt at that right now).

So email me personally if you would like to volunteer to help out LDP.
You yourself pick what you would like to do, but it may wind up taking
over a hundred hours or so before you get it done.  The positive side
is that what you write winds up on hundreds of mirror sites and
eventually, a Google search on your name may result in thousands of
hits.  So what?  In my case, it paid off a little during the dot.com
boom since I was invited to buy stock in VA Linux which shot up 10
times in price the first day it opened, breaking all stock market
records.  But the chance that something like this will happen to you
is very low.  To get to the LDP website go to ours: sgvlug.net and
click on LDP.

			David Lawyer