OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  Positions on the Open Toolkit

    Posted 03-25-2009 21:22
    Dear Friends,
    We are all following this interesting thread. In this memo, I'm
    suggested we give it a recognizable name. 
    
    Part of the issue in front of us is the necessary distinction (I
    believe)in the DITA TC between the DITA specification, which is an
    official OASIS standard, and the DITA Open Toolkit, which is not. I
    wonder if such a distinction might be important for the publication of
    guidelines that would have a substantial influence on DITA adoption? 
    
    Can we develop information that indicates how tools developers are
    supporting the OT without inviting charges of bias? Mary McRae's note
    indicates that OASIS takes no official position on the nature of the
    documents that are official statements from the technical committees (or
    at least it hasn't as yet). I think we might be able to produce a Fact
    Sheet to accompany the Beginner's Guide for Getting Output from DITA(our
    long, awkward working title from today's meeting of the Adoption TC)
    that provides data about tools support for the OT and processing. I
    think that was what the Help SC was trying so valiantly to do. If we
    publish the Fact Sheet in the wiki and link to it from the Guide (which
    we would publish with the OT, then we can invite anyone to add their
    testimonial about their implementation (without advertising -- so must
    be reviewed before added). Would this not be similar to the testimonials
    we now offer about using the DITA 1.2 specification? These are
    statements of fact without judgments attached. 
    
    Let me know what you think. The Adoption TC is committed to providing
    guidance for the OT, obviously with the involvement of Matthew Varghese
    who has assumed responsibility for updating the OT Guide. No one in
    today's discussion felt that the existing OT Guide was taking the right
    direction or had the right audience's in mind.
    
    Our present task is to create a possible TOC for such a Guide based on
    the goals we identify for the different levels of the user community. So
    far, we've identified those levels as 1) techie folks who prefer working
    at the command line 2)ordinary folks who wouldn't dream of command lines
    to save their lives, and 3)intermediate folks who are willing to learn
    the techie stuff if they don't have any other choice.
    
    We envision explaining how to use ANT in very simple terms with code
    that can be cut and pasted. We envision explaining that there are tools
    that hide all of that. We envision providing some very basic
    instructions for modifying the FO to change the look of the output based
    on examples and lines of code.
    
    That was the tenor of this morning's (25 March 2009)discussion. Let me
    know what you think.
    
    Best regards,
    JoAnn
    
    JoAnn Hackos PhD
    President
    Comtech Services, Inc.
    joann.hackos@comtech-serv.com
    Skype joannhackos
    
    
    


  • 2.  RE: [dita] Positions on the Open Toolkit

    Posted 04-13-2009 17:56
    [I cannot post directly to the DITA Adoption TC, but I have
    no objection to someone forwarding this as deemed appropriate.]
    
    While PTC feels that the approach taken by the DITA TC's Help 
    Subcommittee is a reasonable way to provide useful information 
    about specific implementations without including or excluding 
    any particular implementations, we would be uncomfortable if 
    OASIS or any of its TCs were to single out a particular 
    implementation--whether the Open Toolkit or another--for 
    special treatment.  This includes "providing guidance for the 
    OT" that goes beyond guidance that is relevant to any DITA 
    implementation.  Guidance for a particular implementation is 
    not something a DITA TC should undertake to the exclusion of 
    other DITA implementations.
    
    paul
    
    > 


  • 3.  RE: [dita] Positions on the Open Toolkit

    Posted 04-13-2009 18:36
    Hi Paul:
    
    I have forwarded the e-mail to the DITA Adoption TC.
    
    I will reply with my own concerns in a separate e-mail so as not to obstruct the content following:
    
    


  • 4.  RE: [dita] Positions on the Open Toolkit

    Posted 04-13-2009 18:36
    Hi Paul:
    
    I have forwarded the e-mail to the DITA Adoption TC.
    
    I will reply with my own concerns in a separate e-mail so as not to obstruct the content following:
    
    


  • 5.  RE: [dita] Positions on the Open Toolkit

    Posted 04-13-2009 19:12
    I think Paul's e-mail brings up especially valid concerns for vendors. 
    
    Nevertheless, in terms of response, I am admittedly concerned about a chilling effect that vendors could potentially have on early adoption efforts for upcoming specializations such as Learning and Training. 
    
    If we cannot provide sample outputs from any implementation, especially from the Open Toolkit, without concerns of bias, we cannot refer to any outputs whatsoever. If this is the case, we cannot demonstrate any practical outputs from DITA, which is essential in early adoption within the marketplace.
    
    In terms of workload and maintenance, it is not possible for a small individual workgroup or committee to reasonably cover examples of every possible implementation, now and in the future, including the implementation at work in someone's basement today. :-)
    
    In terms of providing practical guidance to evaluators, vendors, and users interested in a nascent specialization, especially in a specialization that would have little formal vendor support in early adoption, I would question excluding everything because we cannot possibly include everything.
    
    I have always thought that the purpose of the Open Toolkit was to provide a reference implementation, both for users and vendors alike at the early stages of adoption. We need to know what the thing is supposed to look like when making evaluations. This would hold true for vendors or content development organizations. I think of the Open Toolkit as a tool for both.
    
    Perhaps the way to proceed for specialization groups is to:
    
    1. Establish an actual or ad hoc representative of the Open Toolkit to provide practical guidance in using the Open Toolkit to support a particular specialization, such as Learning and Training, Help, or whatever.
    
    2. At the same time, invite participating vendors to provide the same kind of parallel guidance for workgroups within OASIS.
    
    3. Provide a general, public announcement outside of OASIS. If other vendors want to provide guidance, they can, either inside or outside of OASIS, now or in the future (obviously, they should be encouraged to join OASIS if they want to contribute now). 
    
    4. Mount all of the examples of practical guidance somewhere common.
    
    No one could be accused of excluding anyone, but adoption efforts could proceed and be of practical, demonstrative use to early adopters and vendors alike.
    
    Just some ideas.
    
    Troy Klukewich
    Information Architect
    Oracle
    
    
    


  • 6.  RE: [dita] Positions on the Open Toolkit

    Posted 04-13-2009 19:12
    I think Paul's e-mail brings up especially valid concerns for vendors. 
    
    Nevertheless, in terms of response, I am admittedly concerned about a chilling effect that vendors could potentially have on early adoption efforts for upcoming specializations such as Learning and Training. 
    
    If we cannot provide sample outputs from any implementation, especially from the Open Toolkit, without concerns of bias, we cannot refer to any outputs whatsoever. If this is the case, we cannot demonstrate any practical outputs from DITA, which is essential in early adoption within the marketplace.
    
    In terms of workload and maintenance, it is not possible for a small individual workgroup or committee to reasonably cover examples of every possible implementation, now and in the future, including the implementation at work in someone's basement today. :-)
    
    In terms of providing practical guidance to evaluators, vendors, and users interested in a nascent specialization, especially in a specialization that would have little formal vendor support in early adoption, I would question excluding everything because we cannot possibly include everything.
    
    I have always thought that the purpose of the Open Toolkit was to provide a reference implementation, both for users and vendors alike at the early stages of adoption. We need to know what the thing is supposed to look like when making evaluations. This would hold true for vendors or content development organizations. I think of the Open Toolkit as a tool for both.
    
    Perhaps the way to proceed for specialization groups is to:
    
    1. Establish an actual or ad hoc representative of the Open Toolkit to provide practical guidance in using the Open Toolkit to support a particular specialization, such as Learning and Training, Help, or whatever.
    
    2. At the same time, invite participating vendors to provide the same kind of parallel guidance for workgroups within OASIS.
    
    3. Provide a general, public announcement outside of OASIS. If other vendors want to provide guidance, they can, either inside or outside of OASIS, now or in the future (obviously, they should be encouraged to join OASIS if they want to contribute now). 
    
    4. Mount all of the examples of practical guidance somewhere common.
    
    No one could be accused of excluding anyone, but adoption efforts could proceed and be of practical, demonstrative use to early adopters and vendors alike.
    
    Just some ideas.
    
    Troy Klukewich
    Information Architect
    Oracle
    
    
    


  • 7.  RE: [dita] Positions on the Open Toolkit

    Posted 04-13-2009 20:17
    Just by way of clarification, I don't believe anyone at PTC
    has a problem with showing output generated from a particular
    implementation as sample output.
    
    What's problematic is for an OASIS TC to provide tutorial
    material on how to use a given implementation.  OASIS is
    a standards organization, not a consulting organization,
    so we shouldn't be providing training on how to use one
    particular implementation.  We should be talking about how
    to use DITA as a standard and as a methodology.
    
    I guess it depends on what you mean by "reference implementation".
    The Open Toolkit is one implementation among several.  It is not
    necessarily a better "reference" in terms of defining DITA than
    any other.  It is not appropriate to use the OT to "know what 
    the thing is supposed to look like when making evaluations",
    because that implies that the OT is right and any deviation
    from what it does is wrong, and I would object to that.  Just
    imagine replacing "Open Toolkit" with "XMetaL" or "Arbortext"
    in your email message below or in JoAnn's message and see how 
    that sounds.
    
    Practical guidance in using the OT is fine, but it is not
    something an OASIS TC should do.  It is something that should
    be done by consultants or the DITA OT group itself outside
    of OASIS.
    
    paul
    
    > 


  • 8.  RE: [dita] Positions on the Open Toolkit

    Posted 04-13-2009 21:40
    Hi Paul:
    
    
    
    Agreed. That's how I've always thought of it. In fact, it is probably more overtly technical and difficult than most implementations by design, given its open, under-the-hood approach.
    
    
    
    Interesting, I think of the Open Toolkit as purely open source and a distinct solution from the commercial implementations with a distinct audience. I think of the OT as a "roll-your-own" solution with rough edges by design. If I don't want a commercial implementation for processing DITA doc types (and some of us don't), I either design my own or use the DITA OT as a basis.
    
    But I can understand where you are coming from as a vendor with current or future implementations in mind. As I am not a vendor, I think of these things differently, especially as an early adopter. I don't rely on commercial tools to show me how to use an open source standard like DITA. If I did, I'd have to wait too long and I wouldn't be early. :-)
    
    
    
    In actual practice, the OT is usually the first thing that a technical implementer like me turns to when commercial tools don't even exist yet. If I want to run Learning and Training, I'm not going to wait until commercial tools like XMetal or Arbortext formally support it (perhaps) in a future release. I'm going to use the OT for an initial test.
    
    It's not so much a matter of whether the OT is better or not, or right or not. As an early adopter, it's the only initial tool that I keep on hand for testing specializations. 
    
    
    
    Thus my concern about a chilling effect within OASIS itself for early adoption efforts now in the works, both for OASIS specialization groups and for the DITA Adoption TC. If these groups cannot provide anything of practical, hands-on value, with tutorial-type information to support early adoption, I would argue that they have no practical value to provide.
    
    I did not understand the restrictions of OASIS as a standards body in this light, but you may well be right. I will seek more guidance from others as your concerns impact an OASIS initiative I am heading up.
    
    I was planning to initiate an approach that would be of use to users and vendors alike for Learning and Training early adopters or evaluators. But if I cannot provide tutorial type information to generate the sample outputs with the OT or other tools as you indicate, then there is nothing to do. 
    
    If I understand you correctly, we in OASIS can only provide abstract standards and hope someone else understands them, implements them, and promotes them on a first-come, first-serve basis, at some point in the future. Adoption is outside the purview of OASIS.
    
    Troy
    
     
    
    


  • 9.  RE: [dita] Positions on the Open Toolkit

    Posted 04-13-2009 21:40
    Hi Paul:
    
    
    
    Agreed. That's how I've always thought of it. In fact, it is probably more overtly technical and difficult than most implementations by design, given its open, under-the-hood approach.
    
    
    
    Interesting, I think of the Open Toolkit as purely open source and a distinct solution from the commercial implementations with a distinct audience. I think of the OT as a "roll-your-own" solution with rough edges by design. If I don't want a commercial implementation for processing DITA doc types (and some of us don't), I either design my own or use the DITA OT as a basis.
    
    But I can understand where you are coming from as a vendor with current or future implementations in mind. As I am not a vendor, I think of these things differently, especially as an early adopter. I don't rely on commercial tools to show me how to use an open source standard like DITA. If I did, I'd have to wait too long and I wouldn't be early. :-)
    
    
    
    In actual practice, the OT is usually the first thing that a technical implementer like me turns to when commercial tools don't even exist yet. If I want to run Learning and Training, I'm not going to wait until commercial tools like XMetal or Arbortext formally support it (perhaps) in a future release. I'm going to use the OT for an initial test.
    
    It's not so much a matter of whether the OT is better or not, or right or not. As an early adopter, it's the only initial tool that I keep on hand for testing specializations. 
    
    
    
    Thus my concern about a chilling effect within OASIS itself for early adoption efforts now in the works, both for OASIS specialization groups and for the DITA Adoption TC. If these groups cannot provide anything of practical, hands-on value, with tutorial-type information to support early adoption, I would argue that they have no practical value to provide.
    
    I did not understand the restrictions of OASIS as a standards body in this light, but you may well be right. I will seek more guidance from others as your concerns impact an OASIS initiative I am heading up.
    
    I was planning to initiate an approach that would be of use to users and vendors alike for Learning and Training early adopters or evaluators. But if I cannot provide tutorial type information to generate the sample outputs with the OT or other tools as you indicate, then there is nothing to do. 
    
    If I understand you correctly, we in OASIS can only provide abstract standards and hope someone else understands them, implements them, and promotes them on a first-come, first-serve basis, at some point in the future. Adoption is outside the purview of OASIS.
    
    Troy