From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: "David C. Mason" , esr@thyrsus.com Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 14:22:00 -0000 Message-ID: <00070614320401.15291@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <20000706131959.A25726@thyrsus.com> X-SW-Source: 2000-q3/msg00031.html Message-ID: <20000706142200.fdEzU-24CW8xRGfHIC0mx2EdyQp6MkjpWqZssBy_PYA@z> On Thu, 06 Jul 2000, David C. Mason wrote: > "Eric S. Raymond" 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