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

["Marc Speyer" <mspeyer@stilo.com>]

Dear Tony,

I am sorry if I made the impression that the DHTG was a product of the DITA Adoption TC which of course is not the case. The Adoption TC originally wanted to use the DHTG as a starting point for DITA adopters. Then there were many comments about the endorsement and objectiveness of the guide which has led to a situation where we needed to find something else. I have read the guide myself almost from start to finish and I think it is a very good starting point if you want to use DITA for help systems. There are how-to's on both the DITA-OT, open source software, and commercial products. It is because of the commercial products that there is some resistance because this where - in a guide for adopters - the objectiveness becomes questionable. I think the guide is a valuable deliverable of the DHSC but since I am not a member of that group I cannot tell.

I am not trying to give an opinion on the appropriateness of the DHTG or to describe what the DHTG is about. If I mentioned it, it was just used as an example within the context of defining focus areas for the group and in the analysis of the course of events. 

Marc Speyer
Stilo International plc

> -----Original Message-----
> From: Tony Self [mailto:tself@hyperwrite.com]
> Sent: Thursday, April 09, 2009 5:58 AM
> To: 'Marc Speyer'; dita-adoption@lists.oasis-open.org
> Subject: RE: [dita-adoption] RE: Tool comparison (Was: Alternative for DITA
> Help Technologies Guide)
> 
> 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
> 
>