[dita-adoption] RE: [dita] Re: [dita-adoption] who complains about complexity of DITA?

[m.y.speyer@inter.nl.net]

I have been following this discussion for some time and felt that I have
to add in my own thoughts too. First of all, the whole discussion about
element count is a non-discussion. In DITA you use only what you need and
the new specialization architecture together with constraint mechanism
make it possible and easier to pick from different domains what you need.
To illustrate my point let�s have a look at the number of pages and
elements (exact counts may differ slightly since this was from an article
I wrote earlier this year). The number of pages has doubled from about 300
pages (194 elements) in version 1.0 to almost 600 pages (291 elements) in
version 1.1 and again doubled to over 1200 pages (528 elements) in version
1.2. This should however not be interpreted as a standard that is growing
unwieldy. For many other standards the number of elements is an indication
of their complexity but this is not the case for DITA. The number of
elements will continue to grow but that should be of no concern because
many of these new elements belong to sector or application specific
domains (vocabularies). A better indication of assessing the complexity in
DITA is by looking at the base elements which only grew by 13% from
version 1.0 in version 1.1 and will grow by only 17% from version 1.1 in
version 1.2.

The new features in DITA 1.2 have come from people using the standard for
some time. Some of the clients I work with couldn�t wait for DITA 1.2 to
become an approved OASIS standard (which it is now thanks to the amazing
work of Kristen Eberlein and the members of the DITA TC). Without features
like keys and keyref you have to resort to messy kludges that will make
the maintenance of the content difficult. So this is a feature that will
directly benefit the author. The same can be said for conref range and
conref push. As we want more things, the standard evolves, and yes may
therefore be perceived as more complex. The challenge will be for the tool
vendors to hide the complexity and I must say some vendors have
implemented the DITA 1.2 features in a very nice way: the user does not
have to know about the underlying mechanism, as it ought to be. The
success of DITA, or any standard for that matter, depends on the support
by the tool vendors.

I have been in the XML publishing business for a long time now (back from
the SGML days) and have seen how the document world has suffered from a
lack of standards. In the beginning we all thought that creating your own
model was the thing to do; from monolithic DTD�s and schemas to even
modular approaches. I have seen publishers investing a lot of money year
after year developing and maintaining their DTD/schema creations. They
wanted to be unique, wanted to have a competitive advantage and all sort
of reasons, only to find out later that instead of an asset they have
created a liability. Standards are good but not necessarily simple,
because users want to do complex things.

Don�t misunderstand me; I am a fan of simplicity too. Things need to be
simple, but that does not mean that the underlying standard or
infrastructure has to be simple too, quite the opposite I dare to say. XML
has been around for some time now and it has always been promoted as the
technology designed for the web, but an interesting development is going
on with sites like Twitter and Foursquare deprecating XML and moving to
JSON. It may well be that XML is going to be replaced by JSON and
microformats, because it is simpler (check out these links:
http://blog.jclark.com/2010/11/xml-vs-web_24.html and
http://xml.coverpages.org/newsletter/news2010-11-18.html#cite2). Although
not likely, but if it happens then only time will tell where that will
leave us as a DITA community.

Marc Speyer
www.sperotech.com


Op Do, 9 december, 2010 2:08 pm schreef Troy Klukewich:
> Re:
>
>
>  
>
>
> <quote>
>
>
> 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.
>
> </quote>
>
>
>  
>
>
> 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
>
>
> Oracle
>
>
>  
>
>
> 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)" <HYPERLINK
> "mailto:bnevin@cisco.com"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.
>
>     /Bruce
>
>