Greetings colleagues
Could I just clarify what sorts of things are covered in the
DITA Help Technologies Guide, as there are a few misconceptions. (And by the
way, there is an Eclipse Help version of the Guide at http://www.helpml.com:8088/help/index.jsp
if you want an easy way of viewing the content.)
The Guide doesn’t review any tools, or make recommendations
on any tools. It doesn’t list any DITA editing tools, and the only
mention of a DITA editing tool is in relation to the Arbortext Digital Media
Publisher (DMP) proprietary Help format. (If you want to create DMP documents,
you have to use PTC Arbortext because it provides access to the specialised DMP
map format. PTC use this DMP format for their own Help systems, but third parties
can choose to build DMP Help too, if they feel it meets their needs. Arbortext
is only mentioned in the context of the DMP format.)
We haven’t otherwise mentioned editors in the Guide
because we’ve focussed on getting Help output from DITA, and not on how
to get DITA content in the first place.
The Guide also mentions many non-DITA commercial products. For
example, many authors wish to deliver their Help through something like the “WebHelp”
output of some (non-DITA) Help Authoring Tools (HATs). The guide shows how you
can have the best of both worlds by authoring in DITA and then doing some post-processing
by importing into a HAT and generating normal (proprietary) WebHelp from the
HAT. Currently, the Guide shows how this can be done using Adobe RoboHelp, and the
next version of the Guide will hopefully provide similar instructions for MadCap
Flare and ComponentOne DocToHelp. (We tried to get these other pathways
included, but couldn’t get anyone to document them!) Again, the Guide is not
written in a way that endorses a product, but rather just provides instructions
and tips for creating feature-rich Help using the commonly-available tools, commercial
and otherwise. The Guide also provides instructions for how to create Microsoft
proprietary Help, open source Eclipse Help, and proprietary AIR Help. The other
tool that is mentioned is my (free) WinANT DITA publishing tool, which is currently
proprietary, but on its way to being open source (via SourceForge). WinANT
reduces the technical barriers to producing reasonable Help from DITA source.
Because we’re not providing an exhaustive list of tools,
there isn’t any particular need to maintain a tools list.
For the Adoption TC, there’s certainly a lot of thinking
to do about the issue of certifying or nominating tools as “DITA-compliant”,
and I think it’s good that the Help Technologies Guide has inadvertently brought
some potential dilemmas to the surface.
Tony Self
From: Troy Klukewich
[mailto:troy.klukewich@oracle.com]
Sent: Thursday, 19 March 2009 8:22 AM
To: dita-adoption@lists.oasis-open.org
Subject: [dita-adoption] RE: [dita] Re: Meeting Request: Issues About
OASIS and OASIS-Approved Publications
Adding items to Su-Laine's points, which I did not have
time to cover in the meeting, now posting just to dita-adoption, perhaps for
further follow-up next week:
I agree that a DITA guide in this format is genuinely useful,
at least for those already using the tools covered, though not necessarily as
an "official" OASIS guide, and not as a tool for evaluation. It
certainly does not pretend to be comprehensive.
In terms of evaluating DITA tools, there have been
some efforts to date, including Bob Doyle's CMS article "XML Editors
Review" and his more recent article in the April 2008 Intercom,
DITA Tools from A to Z. I contacted Bob at one point and he mentioned that
the effort to track the growing list of DITA tools is monumental, even on a
yearly basis.
In addition to any legal or perceptual issues with OASIS
trying to track and review tools in a methodical manner, I question
whether we can handle the scale of such a commitment. It's no problem to track
two tools. Twenty tools is another matter.
As I am a DITA adopter, and not a vendor, I know what I would like.
:-) I have had to test numerous tools on my own, and this is probably
typical amongst companies and individuals evaluating DITA along with new tools.
I really, really liked the idea of a standardized test suite
DITA project for running against tools. It would not have to be a particularly
realistic example, contrary to my desire for a separate, real-world sample. (A
real world sample would not most likely make use of every single major feature
of DITA and would probably look silly if it did.)
I find that when vendors say they support DITA (and no offense here
to the vendors), it doesn't mean much of anything to me. I have to test what
support really means and whether the level of support meets my particular
needs.
From a logistical standpoint, we at OASIS may be in no better
position than to come up with standards, define levels of compliance per some
objective criteria, and possibly indicate what tools pass compliance when
submitted to us. If we are going to take on this role of confirming
compliance, I think the onus should be on vendors to submit on a first come
first serve basis, not for us to find and track.
If we do take on the role of confirming compliance, I think we
should make the process formal and announce it to the general industry via the
usual communication channels for these kinds of processes.
I also think that a test suite would be really useful to vendors
wanting to create or improve tools that support DITA. There have been a
few tools that I have reviewed that--without mentioning names--have not
impressed me with their interpretation and level of DITA-support. I suspect
that if a particular vendor had actually worked from an objective and
full set of criteria along with a test model, they might have implemented
things differently, to the benefit of the market and themselves.
In an ideal world, I'd love to see the Help Guide's hands-on,
real-world approach used on every single DITA tool out there. Such
documentation would be fantastic for companies prototyping solutions and
testing tools. In the end, I do not think it is practical for us to
document every single tool, no matter how valuable. We may simply have to leave
it up to each vendor whether they supply such documentation against a
standardized test suite from OASIS.
On the other hand, I do think of the DITA OT as a lowest common
denominator implementation. When I first evaluated DITA, I went to the source,
then checked vendor solutions. I used the OT as a
comparative baseline. While it would make sense for vendors to cover
their own documentation needs proving how easy it is to use DITA, it would make
sense for OASIS to cover its own open source solution referencing a
standard test suite on equal footing. I do think it would make sense
at the beginning of the material to make clear that the OT is a reference
and one of many implementations, then point people off to some other vehicle
for tool review.
I think it would be fair for us to post such a practical
OT "guide" referencing a standard test suite somewhere, whether
official or unofficial, and invite vendors to submit links to their
own solutions, all on equal footing. And if the vendor solution ends up
looking better than the nuts and bolts DITA OT, so be it (and I hope so,
too).
For me as an evaluator, an OASIS test suite, a standard
hands-on guide to get the reference system running for detailed testing, and
competitive, comparative, parallel information from vendors would be
heaven. In the worst case, I'll take a new tool and run it against the test
suite myself without documentation and see what it can do. Either way, with or
without accompanying documentation for the test suite, I win as an adopter.
-----Original
Message-----
From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
Sent: Wednesday, March 18, 2009 12:44 PM
To: Bruce Nevin (bnevin); Michael Priestley; stan@modularwriting.com;
mary.mcrae@oasis-open.org
Cc: dita@lists.oasis-open.org; tony.self@hyperwrite.com;
dita-adoption@lists.oasis-open.org
Subject: RE: [dita] Re: Meeting Request: Issues About OASIS and
OASIS-Approved Publications
Hi Mary and everyone,
It's been an interesting past few weeks. Below I've tried to
summarize some *potential* issues in publishing OASIS guides to technologies.
Not all of these apply to any discussions we've had about this particular
guide, however I think it is useful to put them on the table as hypothetical
issues for purposes of formulating and clarifying OASIS's general policies on
the publishing of technology guides under its name.
- The public might perceive that the products associated with
subcommittee TC members are given more prominence than the products of
non-members, and consider OASIS to be less credible as a result.
- Vendors whose products have not been included in the guide might
complain that they didn't receive adequate notice about the fact that the
document was being written, and didn't have a fair chance to have their
products considered for inclusion.
- Useful information about a product might be omitted from a
guide in order to make it more palatable to the product vendor who holds a vote
on whether to accept or reject the guide.
- Claims about a particular product may turn out to be false
advertising. If false advertising appears in content published by OASIS, who is
responsible for it?
- Is it a good use of TC time and energy to try to evaluate a
technology guide written by a subcommittee?
- Can a TC provide a meaningful approval of a technology guide
written by a subcommittee if TC members do not have access to some of technologies
described in the guide?
Again, not all of these issues have come up in the discussion
about this particular guide, but these are the types of things that I think are
useful to put on the table for purpose of formulating OASIS policy.
I also want to echo Kris Eberlein’s sentiment appreciating
the effort that has been put into this guide so far by Help SC members. Much of
the information the Help SC has produced is useful to the public; the question
we are trying to address is if and how the OASIS name should be associated with
it.
Best regards,
Su-Laine
Su-Laine
Yeo
Interaction Design Specialist
JustSystems Canada, Inc.
Office: 778-327-6356
syeo@justsystems.com
www.justsystems.com
From: Bruce Nevin (bnevin)
[mailto:bnevin@cisco.com]
Sent: Wednesday, March 18, 2009 11:34 AM
To: Michael Priestley; stan@modularwriting.com
Cc: dita@lists.oasis-open.org; mary.mcrae@oasis-open.org;
tony.self@hyperwrite.com
Subject: RE: [dita] Re: Meeting Request: Issues About OASIS and
OASIS-Approved Publications
Where angels fear ...
Since my organization is a DITA adopter rather than potential
competitor in the vendor space serving adopters, maybe I can dare to be a bit
more forthright.
Representatives of member organizations meet on committees and
subcommittees in a cooperative spirit to establish standards, guidelines, etc.
to the mutual benefit of all.
Might another organization enter such a committee (or view its work
and membership from the outside) and construe that cooperative spirit as
collusion among an anti-competitive cabal?
Surely in the full breadth of OASIS such issues have arisen before
and been addressed. As one possible approach, is "mutual
benefit" defined in the broadest sense somewhere in the OASIS
umbrella such that no one can construe it in a narrow, exclusionary sense, and
can a TC or SC point to that umbrella definition should the issue arise?
/Bruce Nevin
From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Wednesday, March 18, 2009 2:01 PM
To: stan@modularwriting.com
Cc: dita@lists.oasis-open.org; mary.mcrae@oasis-open.org; tony.self@hyperwrite.com
Subject: Re: [dita] Re: Meeting Request: Issues About OASIS and
OASIS-Approved Publications
Hi
Stan,
To
clarify, I don't think anyone suggested that an OASIS member organization would
sue another OASIS member organization. The question was, are there any concerns
about a group of OASIS member organizations writing about the products of other
companies (or writing about some products but not others, for that matter).
So
much for not characterizing the issues in writing :-) But I wanted to correct
the characterization of the chit-chat anyway.
Michael
Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
|
stan@modularwriting.com
03/18/2009
01:23 PM
|
|
To
|
mary.mcrae@oasis-open.org
|
|
cc
|
dita@lists.oasis-open.org,
tony.self@hyperwrite.com
|
|
Subject
|
Re:
[dita] Re: Meeting Request: Issues About OASIS and OASIS-Approved
Publications
|
|
Hi Mary --
Spring is in the air. With chit-chat about OASIS member organizations being
open to suing other OASIS member organizations and OASIS individual members, it
may not be prudent for any individual to characterize the issues in writing
(hence the intentional vagueness in my previous email).
Perhaps the best course would be to have the TC next Tuesday
"approve" the minutes of our meeting yesterday, thereby providing an
appropriate starting place for defining the issues pertinent to the meeting
that we'd like to organize with you.
Sorry ... I wish that it were as simple as summarizing the explicit points of
debate.
Stan
----- Original Message -----
From: "Mary McRae"
To: stan@modularwriting.com
Cc: dita@lists.oasis-open.org, tony.self@hyperwrite.com
Subject: [dita] Re: Meeting Request: Issues About OASIS and OASIS-Approved
Publications
Date: Wed, 18 Mar 2009 00:12:04 -0400
Hi Stan,
It would be most helpful if you could provide the list of issues in
advance so I can make sure to have the right people involved - once I have a
better idea I can look at schedules and see what will work for everyone.
Regards,
Mary
On Tue, Mar 17, 2009 at 8:34 PM, <stan@modularwriting.com>
wrote:
Hi Mary --
In the process of reviewing the DITA Help Technologies Guide (attached), the
DITA Technical Committee bumped into some issues -- some potentially legal --
that are beyond the scope of our TC. We suspect (and hope) that other TCs or
working groups in OASIS have encountered and resolved such issues.
We are hoping that you could set up a concall next week with you and with the
following DITA people:
- su-laine.yeo@justsystems.com
- tony.self@hyperwrite.com
- Micheal Priestley
- Don Day
- Stan Doherty
Two goals for the meeting --
1. Review the issues.
2. Identify from the OASIS side of things possible precedents, resources, and
solution strategies
Thanks,
Stan Doherty
--
Mary P McRae
Manager of TC Administration, OASIS
mary.mcrae@oasis-open.org
voip: 603.232.9090