RE: [dita-adoption] RE: Tool comparison (Was: Alternative for DITA Help Technologies Guide)

["Tony Self" <tself@hyperwrite.com>]

Dear Marc

I feel the urge to clarify some issues relating to the DHSC DITA Help Technologies Guide (DHTG) once more!

The DHTG is a guide to creating Help systems, using the various Help technologies, from DITA source. It doesn't touch at all on how you should author DITA content. The technologies it mentions are Eclipse Help, Microsoft HTML Help, RoboHelp WebHelp, Digital Media Publisher, AIR Help, and various JavaScript-based Help options. None of these are DITA technologies. None of these are DITA tools. The Help Technologies Guide is all about creating Help Systems (ie, User Assistance solutions) from DITA source. 

The DHTG doesn't look at tool selection; not selection of DITA authoring tools, and not selection of Help technologies. It assumes that users know they need to produce, say, context-sensitive HTML Help, and need to know how/if they can do this in a DITA environment. (And again, the DHTG does not include a tools comparison.)

The question that the DHTG tries to answer is one that is not unusual amongst Help authors: "I would kind of like to use DITA, but how can DITA actually be used to create [**insert name of Help technology here**] Help?" I don't think that particular question can be answered unless the Guide mentions [**insert name of Help technology here**].

I'm not disagreeing that there's a need for a DITA Tools Selection Guide, but that idea is not connected in any way with the DITA Help Technologies Guide (a product, by the way, of the DITA Help Subcommittee, not of the Adoption TC).

Regards

Tony Self
Chair, OASIS DITA Help Subcommittee



-----Original Message-----
From: Marc Speyer [mailto:mspeyer@stilo.com] 
Sent: Thursday, 9 April 2009 8:22 AM
To: dita-adoption@lists.oasis-open.org
Subject: [dita-adoption] RE: Tool comparison (Was: Alternative for DITA Help Technologies Guide)

Hi all,

Thanks for the encouraging words on the suggestion for an alternative for the DITA Help Technologies Guide (which is somewhat misleading because what is suggested is really something different). The idea behind this is to help the DITA adopters to select the proper software tools. I agree with Alex that we should stay away from the "actual" software tool comparison because this is what will get us into the same risky position as was perceived with the Help Technologies Guide. What I meant is a selection tool that people can use to figure out what is important to achieve their goals (very close to what Don suggested). The selection would help people to:
1. understand which functional areas are relevant for DITA
2. decide which of these functional areas could be important for them 
3. validate conformance of software tools by means of a test set

It would be up to the DITA adopter if they want to go through a package selection process, e.g. by extracting and sending out questionnaires or something similar to vendors. I would leave it to bloggers, vendor and other sites if they want to maintain a tool ranking based on the selection tool we provide. Most rankings are just a snapshot view anyway with some (unknown) prioritization playing in the background.

So how would people use this selection tool?

Let's take for example a functional area like PDF printing. Using the OT a very important component is the rendering engine, but what if the rendering engine does not support MathML or EPS and some of your content happens to be in this format. And if you are using MathML you need to think of a way to create it, to maintain it, etc. Is it important that the author sees the equation while editing the text of a topic? If the MathML is stored in a CMS do you want to preview it? Should the CMS also create a thumbnail for it? It is quite easy to come up with a lot of functional requirements and most people would say yes to all of them, but there is of course a price to pay for having all of this. The selection tool should provide a way for people to prioritize requirements, for example using the familiar prioritization MosCoW method (Must, Should, Could, Wont). There are often alternatives when a requirement is not met, for example again the MathML issue could be addressed by adding to the pipeline processing a step to convert MathML into a bitmap or SVG. This may introduce some challenges for software packages that have integrated the toolkit and the DITA adopter should be aware of this. Again using the case of MathML and PDF the selection could look like this:

-- start of example ---
Main goal: PDF printing
...
Requirement: MathML support
  Why this requirement?
  When is it important?

  MathML in files referenced from topics
     Standard OT processing => Rendering engine must support MathML
     OT + MathML conversion => list of software libraries + customization steps (pipeline processing)

  MathML embedded in topics
     ...

Sample test set of MathML + expected output
...

Main goal: Online Help
...
-- end of example ---

Of course the above should all be organized in an easy to read way (e.g. using tables for example).

I hope this clarifies things a bit better. 

Regards,

Marc Y. Speyer
Stilo International plc
www.stilo.com