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] 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 specific 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 expose 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 FrameMaker 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? Obviously, 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.


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