OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] RE: [dita-adoption] RE: [dita] who complains about complexityof DITA?

Hi dita-learningspec and dita

This discussion has been interesting and the points raised show an interesting diversity of situations where problems do and don't occur.  My work in relation to DITA has primarily been in the education sector which demonstrates some particular differences but also some approaches in relation to corporate training.  In either case, however, there have not been any significant adoptions of DITA.  The experiences I have had are consistent with previous comments but I would like to make a couple of distinctions and draw attention to some particular issues that I believe are relevant.

1.  DITA itself is complex.  It is not useful for the more technically minded, let alone those with substantial XML expertise, to say that DITA itself is simple or comparatively simple relative to other XML standards.  DITA has rich functionality and the inheritance capability mean that non-technical content developers are intimidated by it.

2.  The richness of DITA is not relevant to all content authors.  More importantly, even with simplified, customized applications and infrasructure a content will creator will need to know about the implications of the choices they make during authoring and how they relate to later stages in the content lifecycle, especially in relation to reuse across different contexts.  Simplification of this is hampered, I believe, by individual topics being overly heavy in metadata and "smarts" that require more detailed knowledge if you really trying to single source content across an organization.  From my experience, individual content items should be as dumb and light as you can make them and aggregations should provide the smarts.

3.  The value is not just in the authoring but also in the processing.  For non-technical users it takes a bit of time for this to sink in.  For use cases where users in the same organization are relatively automous with respect to authoring and output choices (incl. destination formats and styles) it is much harder to tame the relationship between authoring and output.  There is no simple, cost-effective way for small scale content developers to create and process content.  Not that I have found, anyway.  You can get moderate simplicity from some authoring tools but defining output styles, formats etc remains highly problematic unless there is a very large system providing the smarts behind the simple interfaces.

4.  <quote>Moving to structured, topic-based authoring is not business-as-usual. It represents a paradigm shift for any author. We can and should hide as much of the complexity as possible but in the end we need to produce something akin to structure in something resembling topics otherwise it is most probable that we've selected the wrong architecture.</quote> (Rob Hanna).  Absolutely correct, however, doing this with DITA requires a large scale commitment to build an infrastructure within an organization that will meet the requirements of the varied users in that organization.  Organizations that "get it" will not have a problem in making that investment (probably in the normal sequence of "pilot" to "limited" to "enterprise-wide".  The organizations that fit this profile normally have highly structured approaches to content, authorization of content, tightly controlled output guidelines etc.  I have no doubt that DITA can be made reasonably simple for professional content developers.

Implementing DITA in a learning context is highly problematic.  While on the surface of it it would seem of high value for an institution to capture the value of enterprise-wide, single-source publishing, bu the reality is that the autonomy of individuals in the organization and the lack of professionalized content creation resources (in most cases) mean that DITA is often not a good fit.  I have been using alternative content formats in the education sector because they have been more successful, not because they are better, and sometimes because choice has been removed in the short term.  In the medium and longer terms some of the issues will be the same but without the added richness of DITA inheritance.  (I hope that some additional efforts in the near future might bring some alignment with DITA where it makes sense.)

From my experience the complexity issue comes down to a single statement:

There is no suitably simple end-to-end process for non-technical, relatively autonomous content authors to achieve the single-source publishing objectives that are useful to them.

If such use cases are not in scope for DITA then the distinction should be made and communicated.  If they are, the gaps in the simplification of tools (end-to-end) at suitably low cost needs to be addressed.

None of the points above argue that DITA itself is too complex.  It needs to be complex to achieve the stated objectives.  Very few people should be exposed to that complexity and they should all be techies who ensure that the system being used is *appropriately* simple for the content developers in their specific context.

Areas where I believe DITA itself will face challenges stem from the 'dumb and light' topics with smart aggregations and those parts of DITA that are anachronistic and relate to its origins not its future.  There will also be a need to change the approach to metadata and shift to a model where less metadata is embedded in individual topics to more associative model for metadata (maybe something that might also accommodate Contextualized Attention Metadata). In the current model where large amounts of metadata are embedded in topics there could easily be an accumulation of metadata as content is reused in different contexts and increasingly there will be rendering and functional issues arising from that metadata.  Also, content that is used in highly controlled environments and that requires tightly controlled authorization processes will fall foul of those processes if reuse in other contexts does not stricty adhere to the authorization process.


On 8/12/10 6:18 AM, Troy Klukewich wrote:
2777d989-73ee-4aa0-aaee-c99c48ce42b3@default" type="cite">

Hi Paul:


You bring up a good distinction between general tool support versus the needs of a particular implementation. I agree that DITA tool vendors should definitely provide support for the entire kitchen sink, the more the better. General tools, like DITA itself, inherently provide a superset of functionality and elements, even if any one DITA implementation is unlikely to use the entire reach of that superset.


On the other hand, I would argue as a best practice that specific implementations should always use available customization features, either within the tool or within DITA (depending on the architecture), to hide functionality and elements that aren’t actually needed to solve the business issues at hand. This minimalistic approach to implementations reduces complexity, training, and overall ramp up time. (You don’t have to address a myriad of questions about element X if element X isn’t there to ask questions about and this particular implementation doesn’t need element X anyway).


I think a good part of the perception of DITA complexity out there is that when writers/end users are exposed to a large number of elements that don’t apply to their situation, they don’t understand them, so they appear unnecessarily complex. In my historical example, we ended up with a large range of elements, all of which made sense to the writers, so no one complained about complexity or there being too many elements, even though the system had indeed become large and complex versus its origins.


I think the best implementation approach to DITA, regardless of how big the standard is or will become, is start small. Don’t include domains you don’t use. And hide unused elements within the remaining domains using whatever mechanisms are available.


The total superset of DITA is complex, though complaining about it is a bit like complaining about rockets being complex. If you want to fly to the moon, you’re going to need rockets and it’s going to be complex. If you want to pop down the street, a bicycle will do. The strangeness of DITA is that it can be a bicycle or it can be rocket, but initially you are given all the parts of a rocket.




From: Grosso, Paul [mailto:pgrosso@ptc.com]
Sent: Tuesday, December 07, 2010 10:46 AM
To: dita@lists.oasis-open.org; dita-adoption@lists.oasis-open.org
Subject: RE: [dita-adoption] RE: [dita] who complains about complexity of DITA?


Small point regarding:


Most implementers take, I believe, the kitchen sink approach, including most everything they can from the get-go, which of course is going to expose writers to a large number of elements that they probably will never use or should never use, even within a particular domain. This is not the ideal way to implement DITA, though it is probably the easiest, which is a problem in itself.



I believe you are using "implementors" there in the sense of consul! tants or system integrators or whatever you call folks who set up an application for a particular use, in which case your comments could very well be true (though I couldn't possibly comment). 


However, that contrasts with tool (not application) implementors such as PTC (and others, but I don't want to speak for them) who are not taking the easy way out, but are working very hard to support every kitchen sink the DITA TC put into DITA 1.2.  We consider it our duty to do that as much as possible so that application implementors will have the full range of features from which to pick and choose.


On top of that, we try to build into our tools all kinds of configuration and customization features (such as ways to hide certain attributes and/or elements and context sensitive insertion choices and browsers to help with the insertion of topics into maps and so on) to allow application implementors and users to customize our "powerful XML Editors" (that some claim certain users don't want to embrace) so that the users' experience can be optimized for their particular needs.


Like others, I see nothing wrong with a sim! pler, reduced function tool that works with DITA if it solves a user's business need.  But if there were no tools that supported DITA 1.2's kitchen sink, interoperability would suffer, and you couldn't very well call DITA a successful standard.





From: Troy Klukewich [mailto:troy.klukewich@oracle.com]
Sent: Tuesday, 2010 December 07 8:51
To: Dgorman@simplyxml.com; Michael Priestley; Bruce Nevin (bnevin)
Cc: dita@lists.oasis-open.org; dita-adoption@lists.oasis-open.org; ErinF@simplyxml.com; MathiasJ@simplyxml.com
Subject: [dita-adoption] RE: [dita] who complains about complexity of DITA?





It is our premise that implementing a subset of the DITA standard is an acceptable way for large, diverse organizations to (at least initiallly) embrace DITA and to achieve the required ROI to justify the investment beyond Tech Pubs. 



This is really the ideal way to implement DITA even from a purely tech pubs perspective. I think what many consumers do not understand is that DITA supplies a large toolbox of specif! ic tools designed to address specific problems. If an organization does not need to address a specific subset of problems, don’t use those tools (for instance, a specific domain that is not in use at the company). DITA is designed for modularity, though I think more work needs to be done to expose how constraints in particular work for implementers as a best practice even within a particular domain.


The same problem solving approach applies to DITA 1.2. Organizations experiencing specific problems that keyrefs or other new features solve, will readily adopt DITA 1.2 features to solve those problems (I’ve already been involved with two companies  that had to create their own keyref architectures to address these same problems).


Most implementers take, I believe, the kitchen sink approach, including most everything they can from the get-go, which of course is going to expose writers to a large number of elements that they probably will never use or should never use, even within a particular domain. This is not the ideal way to implement DITA, though it is probably the easiest, which is a problem in itself.


Some years ago, pre-DITA, I worked on a custom XML implementation for tech pubs that started with an admittedly small set of XML elements, one could readily argue inadequately small. We simply didn’t have time to take the kitchen sink approach and cover everything we could think of. We started small on purpose and decided to expand the subset based only on valid business justifications to solve identified problems.


After a couple of years and many business justifications later, the system was significantly more sophisticated and complex than when we began, or could have ever imagined. The increased sophistication and complexity was founded on business cases, met real needs, and solved real problems. No one complained about the increased complexity (except maybe for some grumbling developers who had to do the initial work). In! many cases, the writers demanded it, once they understood the potential of the system.


DITA has the advantage/disadvantage! of already being a mature meta-implementation with many years of development behind it. But few companies start with the idea of implementing the smallest possible  subset of functionality that they actually need and then “growing” the system based on further requirements only as they come up.


I think the constraints model is the right way to go. Only expos! e what is needed at the time of knowledge. And if you aren’t sure, or don’t know, don’t expose it. Yes, issues will arise. At that time, identify the specific problem and expose what is needed from the greater DITA toolset to solve it. And if DITA doesn’t already solve it, develop something yourself on top of the open framework if the business justification warrants the development cost.


Troy Klukewich

Information Architect



From: Dgorman@simplyxml.com [mailto:Dgorman@simplyxml.com]
Sent: Monday, December 06, 2010 11:15 PM
To: Michael Priestley; Bruce Nevin (bnevin)
Cc: dita@lists.oasis-open.org; dita-adoption@lists.oasis-open.org; ErinF@simplyxml.com; MathiasJ@simplyxml.com
Subject: RE: [dita] who complains about complexity of DITA?


i'm afraid we may have caused some of this ruckus!  We recently presented a session at DITA Europe focused on bringing DITA to the enterpirse at large.  The presentation and our concept of "Simply DITA" has been extremely well received, even by some organizations who had previously turned away from DITA because of its perceived complexity.  We are thrilled at the level of interest we have generated in DITA.


At Simply XML, we have been pushing the opportunity for DITA outside of Tech Pubs organizations.  While we fully appreciate the elegance and scope of possibilities of DITA within large Tech Pubs organizations, we also see the potential for DITA to become a standard for single source publishing and multi-channel publishing across the enterprise at large.  For this to happen organizations need to adopt both XML and topic-based authoring.  DITA has great potential here, but many non-tech pubs organizations have evaluated DITA and found the realities of implementation to be too costly for the return involved.


To make DITA and enterprise standard, it needs to be embraced outside of Tech Pubs.  For this to happen, tools and processes must be simple and business-oriented.  We know that the milions of authors outside of Tech Pubs will not spend the time to learn all the complexities of DITA, nor will they embrace the powerful XML Editors.  They want a better, easier way to author the content they are familiar with.  They and their organizatons will not learn all the intracacies of DITA, only to determine and use an acceptable subset.  They want smeoneo to decide for them and provide them with relevant tools and training..


It is our premise that implementing a subset of the DITA standard is an acceptable way for large, diverse organizations to (at least initiallly) embrace DITA and to achieve the required ROI to justify the investment beyond Tech Pubs.  We further propose that the very large number of authors who generate structured and semi-structured content (polices and procedure, training materials, documentation from small groups, marketing materials and sales materials) will not find it cost effective to both learn about DITA and author with a traditional XML editor. These authors work in MS Word which may be as powerful as an XML, editor, but it is known and used.


So, we are helping our customers implement DITA from MS Word and aim to allow transparency of DITA and XML with Tech Pubs. This includes perfect round tripping from MS Word to the more complex DITA editors and back, when a Simplified DITA Schema is used. It includes one-way MS Word to DITA when elements beyond Topic, Task, Reference, Concept and DITA Map are needed.  We are also suggesting that, for some applications, organizations would benefit by initially embracing only the DITA Topic. 


Our custo! mers are rapidly embracing what we call Simply DITA which is an XSD that permits the vast majority or even all Documentaiton, Policies and Procedures, Training materials, etc. to be authored with a subset of the DITA Standard.  The Simply DITA schema is a subset of DITA the elements we feel are necessary to creat DITA Topics, DITA Tasks, DITA Concepts, DITA References, and DITa Maps.  It is important for authors to understand the architecture behind their writing, but they are focused, not on the underlying standard and XML, but rather on the efficient generation of high quality content.  As a tools vendor, having our cusotmers work with MS Word and the DITA stnadard is not as simple as using the schema with XMetaL, or Arbortext Editor, or FrameMa! ker 9.  We are doing our best to hide the XML and DITA from the content creator, but to always generate Valid DITA.  To do this, we are deep inside MS Word, controlling what the author can do at a number of levels.


We do not want to in any way hinder the work being done with DITA in larger or more technically focused work groups and we applaud the work being done by the DITA Committees.  It is our hope that our DITA solution beyond Tech Pubs is complementary to this effort and we truly believe that the DITA standard will endure once entire organizations adopt it on a large scale.


Like most of you, we fully believe in the promise of DITA and want to do everything in our power to have it succeed as a very broad standard where similar historical effort in the SGML and DocBook world have failed.


We welcome your comments and input.  I have enclosed an outline of the elements we have implemented with Simply DITA and a related White Paper.



From: Michael Priestley [mpriestl@ca.ibm.com]
Sent: Monday, December 06, 2010 9:16 AM
To: Bruce Nevin (bnevin)
Cc: dita@lists.oasis-open.org; dita-adoption@lists.oasis-open.org
Subject: Re: [dita] who complains about complexity of DITA?

I'm also curious about this. Even before we had constraints, we had basic DITA modularity, which lets you include or exclude whole ! domains of elements at a time. And the doctypes we package with the spec do exactly that.

Simple number of elements in the spec as a whole shouldn't be a measure of complexity for either authors or architects, since you only include or work with the elements that matter for your domain. For example, the learning and training specializations don't increase complexity for authors or architects in basic tech comm.

So do we really have a complexity problem, that is it's too hard to use DITA or create new DITA specializations? Or do we have a communication problem, about how to use DITA (start small, include what you need, don't try to use stuf! f you don't need)? Or are there other problems, outside the domain of the spec, like customizing processing flows, that get reflected back on the spec even though it's really something outside our control?

I don't mean to dismiss complaints about complexity, but like you I think we need to understand the actual motivations/causes of the complaints before we can usefully react.

Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect


"Bruce Nevin (bnevin)" <bnevin@cisco.com>


<dita@lists.oasis-open.org>, <dita-adoption@lists.oasis-open.org>


12/06/2010 11:01 AM


[dita] who complains about complexity of DITA?


Are we entirely clear about the use contexts in which users find the number of elements onerous or confusing? Obvi! ously, the authoring environment is one.  But do architects also object? Do the tools vendors object? This seems less likely to me, but it's not something to guess, we should find out. And is that (the number of elements) the only complexity that they object to?

The constraints mechanism can neatly address the perceived complexity in the authoring environment. (Be it noted that existing mechanisms provided by [some?] authoring tools to hide elements from authors apparently do not reduce these complaints, maybe because the complaints come from users who don't make use of them.) But creating and managing constraints is another layer for architects and designers to deal with.


Allyn J Radford
Managing Director
Learnilities Pty Ltd

Solution Architecture Consulting
Standards-based eLearning Systems and Content
Digital Content Exchange Planning and Development

Phone: +61 (0)3 9751 0730
Mob:   +61 (0)419 009 320

[Please Note:  When traveling I often have to use the Gmail outgoing smtp server and relevant details to send 'legal' email without being  blocked by anti-spam settings.  Please only reply to my normal email address.]
This e-mail message contains confidential information. If the reader is not the  intended recipient or an agent responsible for delivering it to the intended recipient, you are hereby notified that you have received this message in error  and that any review, dissemination, distribution, or copying of this message is strictly prohibited.

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]