Re: [dita-adoption] RE: [dita] Re: Meeting Request: Issues About OASIS and OASIS-Approved Publications

["David J. B. Hollis" <dhollis@AandOConsultancy.ltd.uk>]

Gershon - please forward to DITA TC.


Some background reading may be useful for some folk.

http://hat-matrix.com/tools_list/
http://hat-matrix.com/vendors/

There are a couple of interesting points:

1. The list doesn't include the 'usual suspect' XML editors, although  
some tools are a part of suites which do.

2. A number of these HAT vendors are taking a serious interest in DITA.

It's an obvious point to make, really, but single-sourcing is having  
major repercussions by blurring the boundaries across the whole  
'publishing' industry - from print to help and everything in between.  
DITA is obviously a key part of that.

 From an adoption perspective, I saw an interesting blog recently:

http://www.author-it.com/blog/2008/12/03/moving-to-structured-content-in-a-crazy-ad-hoc-world/

HTH
David


> 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 athttp://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.
>
> Troy
>
>
>
>
>
>
>
>
>
>
> -----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