On Sat, 14 Jun 2014 22:38:40 +0100, Orchid Win7 v1 wrote:

>> 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. 

From what I've seen, that belief has a good foundation.

> The question, of course, is whether I can find the time to do
> this.

That is always a challenge when it's not part of the official duties.

> 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.

You might do a little research on "targeted documentation."  The idea 
behind this is to break documentation into procedures, concepts, and 
reference material - something that DITA is actually designed around.

>> 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.

True.

> ...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.

It's "trivial" once you understand it, just like using InDesign, 
FrameMaker, or Blender, though, it's got a learning curve, and it's not 
something you're going to understand overnight.

> 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.

One of the nice things about working with DITA is that you can easily 
transform it (with the right tools) to XHTML or HTML.  You can also get a 
really slick publication out of it, because it can easily be transformed 
to a PDF or other e-Book format (I'm partial to EPUB myself, and if 
you're generating HTML, EPUB isn't much of a stretch).

Jim
-- 
"I learned long ago, never to wrestle with a pig. You get dirty, and 
besides, the pig likes it." - George Bernard Shaw

Post a reply to this message