> But a tool alone isn't (hopefully obviously) going to give you great
> documentation.  You also need technical writers (at least one).

I'd like to take a stab at this myself. I believe I'm quite a good 
writer. The question, of course, is whether I can find the time to do this.

Trouble is, currently the documentation sucks, but nobody has the time 
to produce something better, so we're just doing minor tweaks to it 
whenever the product changes. Really the entire thing wants to be thrown 
in the bin and somebody to start again. But if I turn up and go "hey, 
here's the new manual" and it's *not* as shiny and pretty to look at as 
the old one... nobody tell take any notice.

> The nice thing about using an XML standard like DITA is that you can use
> xslt to transform it, so if you need to customise the transformation,
> it's trivial to do - if you know xslt.

DocBook is an XML standard. So - in theory - it's "trivial" to make it 
do what you want.

...in reality, I found it hellishly difficult to change even the tiniest 
detail about it. Perhaps it would be simpler to rewrite the XSLT from 
scratch rather than try to figure out how it works. And maybe, just 
maybe, the XML-FO processor I'm using just can't be convinced to produce 
nice output.

For that matter, we could write documentation in HTML and apply lashings 
of CSS to it. You can do paper-specific CSS settings and so forth, and 
everybody in the room already knows how CSS and HTML work. Again, the 
trouble is, you'll never get it to look slick and polished.

Post a reply to this message