On Sat, 14 Jun 2014 12:42:55 +0100, Orchid Win7 v1 wrote:

> Does anybody here know anything about Adobe InDesign?

Not specifically about InDesign - but FrameMaker isn't that different 
from it, I hear - and both products have a pretty steep learning curve 
that - once you know how the product works - actually ends up making 
sense.  Kind of like the first few releases of Blender after it was made 
an open source project (it had been a commercial product prior to that).

From Adobe's suite, FrameMaker is the tool of choice for producing 
documentation.  There are other products out there, but Adobe is pretty 
well entrenched - but that seems to be changing.  I know a few companies 
that use a product called Madcap Flare who really like it, but DITA is 
also becoming a lot more popular for information structuring and 
documentation.  It's a format rather than a tool, but there are some good 
tools for creating DITA (including, I understand, FrameMaker 12 - Frame 
11 isn't so good with it, though - but it can read and write DITA files).

As it happens, what I'm doing right now is a lot of this type of 
documentation work.  The client I'm working with right now has a mix of 
tools used for writing and publishing the documentation, but the 
direction is to simplify this because production is way too complicated 
and has too many moving parts from different vendors.

Take a look at DITA tools - I'm going to start looking at oXygen (an 
editor - well, an IDE) fairly soon.  One of the client's products is 
documented using DITA, and the guy who handles it seems to have a very 
good workflow.  oXygen can produce PDFs, XHTML, or pretty much whatever 
sort of output you want.

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

A good technical writer isn't akin to "Tina the Tech Writer" in Dilbert, 
but rather is someone who can learn and understand the product being 
documented, and can not only write about it, but can become an expert in 
using it *in order to write about it*.

Using DITA - which is an XML standard - means that putting the files in a 
source control management system works the way you'd expect.  I've done 
FrameMaker with various SCM tools, and while you don't get diffs, the 
version control is helpful.  But doing it in DITA means you can have some 
of those additional benefits.

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.

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