Re: I'm trying to set up docbook-tools...

[Eric Lee Green <eric at badtux dot org>]

On Thu, 06 Jul 2000, Mark Galassi wrote:
> Kendall> As for actually setting up and installing the various
>     Kendall> permutations of the free tool chain, I just don't see why
>     Kendall> it's *so* hard for someone with a bit of technical
>     Kendall> ability or experience.
 
> It isn't.  The person who started this thread said there was no
> tutorial which includes setting up the tools, but there actually was.
> Although things are out of date, this whole thread is mostly
> unnecessary.

Futile, perhaps. Unnecessary, no.  I am constantly fighting The Cult Of
Obscurity both on the job and off it, because so many good technical people
just don't see what's wrong with their documentation and programming.  "It
makes sense to me, other people must just be stupid" is the attitude of the
typical adherent of the Cult of Obscurity.  I sometimes have to fuss at my own
co-workers about "Look, I don't care about details x, y, and z, I, the
hypothetical the end user, just want to get job 'n' done",  and I'm certainly
not going to be reticient about doing the same elsewhere,  even if I'm not being
paid to do it elsewhere :-).  

People do not care about elegance. They do not care about how terse and formal
the language is surrounding a topic. They just want to get a job done with as
few keystrokes or mouse clicks as possible, and learning as few details as
possible to do it. This is one place where Lamport's LaTeX book shines (despite
how aweful it is otherwise), the first thing he does is say, "Here is how you
write a letter in LaTeX." What genius! 

Regarding Norm Walsh's book: the biggest problem was a lack of examples of how
to use DocBook to create entire documents.  There's reasonably good examples of
the use of many of the individual elements, but nothing like where Lamport
says, "Here is how you create a document. Here is how you create a letter.
Here is how to create a document that has a table in it." Lamport's LaTeX book
sucks... but it sucks in a way that lets most people write simple documents
after reading it. 

Note that I'm not calling the SGML crowd stupid.  I'm not saying that their
documentation "sucks" for people who are already initiated into the Cult Of
SGML. What I'm saying is that a) there's a paucity of documentation about how
to Get The Job Done, the only one I know about is the FreeBSD one, and b) there
has been a lack of attention to Getting The Job Done on the part of the
SGML community as a whole, they have been absorbed in the technical excellence
of SGML, the theoretical possibilities of parsing SGML, the stylistic elegance
of DSSL and stylesheet languages, whilst ignoring the whole point of the
exercise. I realize this is not an attitude that is restricted to the SGML
crowd. This sort of attitude is rampant in the computer biz, those of us who
have a good understanding of end user wants and needs are always the minority,
and those of us with both technical skills and writing skills are even rarer.
But, as the other Eric mentioned, this sort of attitude is also what kept SGML
from sweeping the world over the last five years, and is what basically has
killed SGML (with the exception of the HTML DTD and XML subset, the former of
which isn't really SGML anymore).  

'Nuff said. I'm sure I'll find many more flames in my mailbox from adherents of
the Highly Theoretical Cult of SGML Gurus.  But (shrug), when it comes to
document production, I'm an end user. I design tape backup and related software
for a living, not documentation tools.  All I want to do is to get a job done.
I don't CARE about how elegant DSSL is, or how flexible the Docbook DTD is...
it's a tool, for cryin' out loud, not a religion.  And if it doesn't Do The
Job, I'll dump it and use some other tool. Which, apparently, has been the
conclusion of most others who would use SGML, too, with the exception of a few
of the Open Source projects which use it because that's what the LinuxDoc
project uses. 

 -- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org