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

[Eric Lee Green <eric@badtux.org>]

On Thu, 06 Jul 2000, David C. Mason wrote:
> "Eric S. Raymond" <esr@thyrsus.com> writes:
> > Anyone not already eyebrow-deep in the dysfunctional culture surrounding
> > this software would realize that this lacuna makes the rest of the 
> > chapter a bad joke.
>
> It is very easy to blame the SGML community for the problems inherent
> to understanding the technology, it is not as easy to lend a hand. Why
> is that? Do hackers think that documentation tools are beneath them
> until they actually have to use them?

Well, unfortunate but true, most hackers are no good at documentation. This
applies to SGML software creators as well :-(. 

Equally unfortunate but true, most hackers have no idea how end users think,
and thus have no idea how to create software that is easy to understand and
easy to use that solves problems that end users actually have.  They tend to
get caught up in making the software super-flexible and super-swiss-knife,
which is nice but not at the expense of ease of solving particular problems.  I
had to fight for the concept of "click this single button, and it does what 90%
of users want out of our software" when it came to prototyping a potential
future product, because the hacker who designed the thing had a screen
cluttered with stuff that would confuse the typical end user and which was not
intuitive at all. But it made sense to him. He didn't understand that most
people are not hackers and don't think like hackers. 

Finally:  those of us who are actually being paid to write documentation rarely
are getting paid to write documentation tools at the same time, and in most
cases even writing documentation is not our full-time job (I write
documentation as part of designing software -- you know, requirements docs,
functional specifications, design docs, class heirarchy docs, etc.). In
addition, we're often fighting pointy-haired bosses who want us to use
Microsoft Word or StarOffice or whatever "standard" office suite the
corporation has adopted, and who (having never written anything larger than
a letter) don't understand that structured document layout systems are much more
appropriate for technical documentation.  To put the blame on the end user for
the poor state of Docbook/SGML documentation and tools is a case of blaming the
victim... we're just out here trying to do a job, not fight religious wars, and
we have enough trouble getting permission to use any kind of SDL system without
having to fight a buggy one as well.  As it is, I have to continually justify
to my bosses my use of DocBook... they don't understand why I would want to use
a SDL instead of the "corporate standard" office suite. Now you're going to
blame me for the fact that I'm getting "-999" for half the page numbers in my
index?!  Sad but true, here in the real world the pointy haired boss's response
to problems that we have generating documentation with the Docbook tools is
"quit that Docbook BS and use Microsoft Word [StarOffice, WordPerfect, etc.]
like the rest of us."  

WHich is why my next set of documentation is going to be using LyX/LaTeX. The
tools work, they work reliably, they've worked reliably for years and years and
years, they're not ideal but they get the job done and dammit, that's all I
care about. And that's why SGML has remained a cult rather than a real solution
for most people's documentation problems. 

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