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-adoption] RE: [dita] Re: [dita-adoption] who complainsabout complexity of DITA?

I think Troy raises an important issue:


Information architecture/content architecture/semantic structure versus XML: You can argue that XML overall and DITA XML specifically is first of all an excellent way to persist the information architecture/semantic structure described by the DITA standard.


Take an example: An "OK" button in some software product. To get high-quality, reusable content, the author/writer may need to make sure the characters "OK" gets marked up as a user interface control.


What the writer does NOT necessarily need to know is: Will this be stored as "…<uicontrol>OK</uicontrol>…"  (the correct DITA element), or is it stored as "…<ph type="uicontrol">OK</ph>…" (an attribute on another element - not the DITA way).  


If the tool used by the writer provides a "UI Control" button or drop-down command - that may be all that is needed. The tool can take care that this gets persisted correctly to DITA XML  and the writer does not actually need to know that XML is even involved in this, let alone how exactly it is implemented in XML.


This still leaves us with the huge task of making sure writers understand the content architecture and the semantics. And that is QUITE a task, even without adding XML into the equation.


Steffen Frederiksen

DITA Exchange  


From: Troy Klukewich [mailto:troy.klukewich@oracle.com]
Sent: Thursday, December 09, 2010 14:08
To: dita@lists.oasis-open.org; dita-adoption@lists.oasis-open.org
Subject: [dita-adoption] RE: [dita] Re: [dita-adoption] who complains about complexity of DITA?





From my perspective as a consultant speaking to customers about DITA in non tech doc areas there is a common theme of not wanting to push knowledge of XML onto users at all.



There have been a couple of comments in this excellent thread about hiding XML completely from users outside of tech pubs, but I think this possibility is highly dependent upon the nature of the domain. For domains with high semantic content, exposure to element tags that have meaning (as opposed to mere formatting) is critical to the functioning of an XML-based system.


Perhaps a domain with low semantic content, like a fiction book, which generally will need mostly structural elements (chapters, paragraphs, etc.), very little exposure to elements would be necessary because there are a minimum of elements to begin with and some of the tagging can be automated (such as for the multitude of paragraphs).


Diving back into tech pubs for a moment, I worked on an API system once where XML elements described various properties, methods, and events, which were then tied back to the object hierarchy and checked with reports. In this scenario, there is no way that writers cannot be exposed to XML elements, as they must use XML elements and attributes with semantic meaning to properly tag the API references. The value of this exercise was that we could then keep tens of thousands of critical references up-to-date with highly accurate error reporting run every build (every day).


Outside of tech pubs, I can imagine scenarios where semantic tagging is valuable (the machine industry springs to mind). Again, I think the key is that the semantic tags must make sense to the user. If they make sense and apply 1:1 to their domain of expertise, they aren’t so “complicated” or hard to understand.


I do like the idea of always simplifying DITA in an implementation to the lowest number of necessary elements, then using specialization to describe a set of semantic tags that are peculiar to the enterprise at hand, assuming of course that semantic tagging provides expressed value (like in my error reporting example to keep critical references up-to-date). This to me is a “standard” model, even if hardly anyone actually follows it. Though, by not following it, we inevitably get complaints about complexity and non-applicability of numerous default elements.


There is a great opportunity here for vendors. I would love to see DITA tools that allow you to easily mix and match domains, turn off non-requisite elements within a domain to simplify the applied model, and then provide easy specialization to build custom elements with specific meaning to the organization. This, to me, is what DITA is all about.


DITA isn’t Word and Word should not be the model nor the ideal. There is an implementation element that should apply to every instance to garner the most precision and value from DITA. Otherwise, we’re just regurgitating the desktop publishing model where users are provided with a multitude of fonts and features they never use or should never use.


Troy Klukewich

Information Architect



From: Mark Poston [mailto:mark.poston@mekon.com]
Sent: Wednesday, December 08, 2010 5:37 PM
To: Bruce Nevin (bnevin)
Cc: dita@lists.oasis-open.org; dita-adoption@lists.oasis-open.org
Subject: [dita] Re: [dita-adoption] who complains about complexity of DITA?


From my perspective as a consultant speaking to customers about DITA in non tech doc areas there is a common theme of not wanting to push knowledge of XML onto users at all.


It's easy for us to suggest that DITA will solve all sorts of problems, but when it comes down to it, the practicalities of doing so are always a lot more complex.


A big challenge to start with is convincing an organisation that XML is the way to go. Without the tools and infrastructure in place there's always going to be a difficult road ahead. For wider corporate use there are challenges from IT departments to accept such changes unless they already fit into an existing IT system - quite often based on Microsoft technologies.


Tech docs teams have generally been a little easier to provide solutions for as their requirements have previously fallen outside of any corporate systems and are for only a smaller closed group of users. This is becoming less the case now.


Overcoming these challenge means that solutions need to be provided that will address the different types of user's needs - considering their user personas if you like.


The work of the BusDocs sub committee is taking a step towards this, and that is likely to introduce more types of content that meet specific needs of different areas in the business. This is very useful work but when it comes down to it, it still ends up being about the tools that are used and the education that is required to adopt them.


For me, for DITA to become successful outside of tech pubs, the focus needs to be on tool vendors taking away the need to know anything about XML and using DITA as the hidden enabler of a content architecture. This brings about the need for DITA-aware tools where XML is never seen - of course there are some of these already (for example Quark XML Author springs to mind).


For many users, features such as conref, keyref, constraints, reltables are too technical for them - these need to described in a context that is appropriate to them and their particular use case, or not described at all as it doesn't actually matter. As a vendor, architect or system integrator they are, again, the enabler - just like a programming language is an enabler to providing a software solution to a customer.


These user friendly descriptions are what the DITA Adoption committee can help with, along with their work on defining benefits of DITA for different audiences.


My concern is that as DITA grows, and it will only continue to grow, it becomes such a complex standard that it will gain a reputation as being as such and perceived as an expensive thing to implement. This is, of course, completely the opposite to the original reason for recommending DITA as an option to tech pubs team, as vendors were able to quickly support and therefore provide a more cost effective solution with, quite often, easily identifiable return on investment.


As the DITA standard grows so to are the requirements for vendors to support it, making XML authoring tools and other systems do more than they were originally intended to do. I am not a tool vendor but I can imagine that implementing the new con ref and key ref features (for example) aren't that straight forward. I just hope that there is still the interoperability between tools now that DITA is not just about parsing XML but also has requires a complex application layer on top of it to implement its features.


Personally, I would like to see an open source DITA interop framework that allows tool vendors to use a common library that implements features in the standard. This can then be integrated into tools in a consistent manner. As the standard grows, this framework would provide the processing logic for DITA's features. It's partly there in the DITA Open Toolkit already ... Which is developed hand in hand with the standard itself.


A long-winded response but I hope provides some useful discussion points.


Kind regards


Mark Poston

Mekon Ltd.

Sent from my iPad

On 6 Dec 2010, at 15:59, "Bruce Nevin (bnevin)" <bnevin@cisco.com> wrote:

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]