Subject:
Re: docs
From:
"Rodolfo J. Paiz" ####@####.####
Date:
1 Nov 2003 23:56:12 -0000
Message-Id: <6.0.0.22.0.20031101172823.024a4a58@mail.simpaticus.com>
At 13:07 11/1/2003, Saqib Ali wrote:
>Here is what I would like to see happen:
>
>1)Once the author is done writing the document [...]
>
>2)While the author is composing the document [...]
I just got here recently, after a few years of using Linux on small servers
and groaning that there were either no docs to learn from, or existing docs
that seemed to be usually seriously outdated. Finally, having derived a
great deal of satisfaction and benefit from using Linux, I decided that I
_had_ to help somehow and that, with my excellent writing skills, teaching
mentality, and nonexistent programming abilities, the single best way in
which I could contribute was to write good documentation. So my humble
opinion may be ignorant and irrelevant, or perhaps because of my
circumstances very useful to you in this discussion. Excuse some rambling.
First and foremost, I find that there are 100 people who want to _use_
Linux for every one person who wants to _learn_ Linux. And even inside the
"want to learn Linux" population, there is a huge majority that does not
have--and does not want to acquire--the technical abilities to compile
their own programs, patch and recompile a kernel, and other little niceties
which serious geeks take for granted and are sometimes even proud of, as
though facing some digital rite of passage. It is this majority (the users
and the learners who are not and never want to be geeks) whom I feel is
being underserved. I am in this market segment, solidly so.
Second, and having concluded that the user and non-geek learner needs to
have better documentation (or perhaps just documentation better adapted to
his/her needs), I find that setting oneself up to write documentation is
overly difficult. The LDP Author's HOWTO and nearly every other document I
have found on the subject starts with "download, configure, make, and
install this bunch of stuff...", when for example Red Hat Linux has all
this stuff already, in RPM format.
It took me DAYS to be able to write my first functional SGML document, and
first I had to go through a miserable experience with the tools for
converting XML to HTML and other formats, at which task I failed utterly.
Having finally gotten a basic SGML doc going, it took me quite a bit of
tinkering to get single- and multiple-page HTML to work as I desired. I am
_still_ working on setting up PDF output, and all of this effort should be
going into WRITING.
Suggestions I would make to the LDP, in no particular order:
* Determine a "core" set of HOWTO documents that most beginners
need nowadas. That may be networking, cable modems, DSL, and a ton of
others, but not Ethernet bridging or CMU Sphinx for example. Make sure that
these documents are marked as primary, reviewed frequently, and kept up to
date. Make them easy to find for newbies.
* When possible, and with emphasis on the "core" documents
mentioned above, add some examples and step-by-step instructions for a few
actual, recent, real-world configurations. For example, in setting up
networking, I think details of GUI and text mode configuration on Red Hat
Linux 9, Fedora Linux Core 1, and the latest Mandrake and Debian stable
releases would be a godsend for many users. Of course the "download,
ungzip, untar, configure, make, install" instructions can stay... but I
would guess that 80% of the readership or more would prefer to use the
package manager included with their favorite Linux distro.
* Make it easier for new authors to get going! Broaden the
available pool of authors. Take the above suggestion for the LDP Author's
Guide, PLEASE. Give me instructions that I can follow in 10 minutes to be
done writing SGML and XML on a Red Hat, Fedora, Debian, or Mandrake system
in 10 minutes or less. Even better, get someone at Red Hat to make an RPM
package which contains the LDP dsl, a simple set of instructions, and some
simple scripts like the "docbook2html" script, and which requires every
other necessary package (docbook-utils, openjade, etc.). Then, with a
single "rpm -Uvh ldp-author-tools.noarch.rpm" I'm up and running. The more
I think about this, the more I want it. <smile>
* The online validator mentioned, and the online tools to test
output in various formats, sound like a wonderful thing. Do not use them
only for submission or for CVS (whatever that is)... let people like me use
them to test out stuff while it's in process! If you do this, then some
authors can avoid the whole tools setup issue altogether. Write SGML/XML
code in a text editor, submit to the validator, submit to the output test
tools, repeat. Heck, you could even automatically pass any error-free doc
from the validator to the output creator (Cocoon or openjade, whatever),
and put the output documents in a particular directory on the FTP server so
the writer can go get them. Delete every created directory 24 hours later
so your server doesn't fill up with junk.
* Note which documents are stale or old. It is frustrating to get
a HOWTO these days that deals with features of Red Hat Linux 5.2 or 2.0
kernels. I know not everything can be kept up to date, but it would save me
and others a boat load of time if I know what isn't recent (has not been
updated in a year, for example).
Hopefully some of this is useful to you all. Count on me being around and
trying to help, although as yet I have little ability to do so. I will
continue learning, though.
--
Rodolfo J. Paiz
####@####.####
