DITA Perceptions

Use this page to organize and capture the unfolding discussion about how to manage the perception that DITA is too complex.

Working Resolutions

Item

Owner

Description

1

DITA Adoption TC

The DITA Adoption TC should recruit more people to get involved with writing articles about DITA. Contributors (ideally) need to be active members of the Adoption TC, although there are opportunities for collaboration. For example, perhaps a TC member can work up a set of working examples on a feature prior to handing that off to an Adoption TC person for doing a write-up.

2

DITA TC

The DITA TC should for DITA 1.3 make it easier to create subsets of the DITA documentation. Robert commented that there is almost certainly room for better documentation subsetting with DITA 1.3. He would be involved with doing the implementation work, but needs other people to offer suggestions and insights on what to do.

3

DITA TC

The DITA TC should make Jarno's DTD/Schema shell generator more widely available and officially supported.

4

DITA TC

The DITA TC should create default document types that include fewer domains a la the base topic.

5

DITA TC

The DITA TC should make specialization easier (new rules, tools, auditing aids). Fir DITA 1.3 - Michael Priestley summarized some thoughts that he has been having about building into DITA 1.3 a template-based interface against a subset of DITA features that would allow users to pick and choose what they would like to see included in a constraint. This completed template could be exported to multiple tool environments. A dedicated working group would be one approach to getting this done.

6

DITA TC

The DITA TC should provide a repository of well-known specializations. JoAnn, Robert, and Michael will get together to figure out how to make the specialization repository work, whether it be an extension of dita.xml.org or a Sourceforge submission. Figuring out how to search them and classify/rate them would be important. Rating guidelines for authors and submitters will be needed.

7

DITA Adoption TC

The DITA Adoption TC should develop a feature article addressing "what is the most basic set of DITA features" would be useful for people learning DITA.

8

DITA TC

The DTA TC should review alternative "views" of the DITA architecture in order to determine if there is a better way to capture and present the architecture to existing and new users. For example, reviewing Rob Hanna's proposal about abstract classes or other notions of type hierarchies might serve as a starting point.

9

DITA TC

The DITA TC should assist in providing new users with a "minimalist" implementation of DITA by developing a starter set of DTDs and constraints. Hand this off to DITA-Adoption-TC. Michael and Don are interested in participating as a skunkworks activity within the TC. Members of the TC and of the BusDocs SC are solicited to participate and perhaps own.

10

DITA Adoption TC

The DITA Adoption TC should leverage the to-be-developed "starter set" of DTDs/constraints and promote awareness of this "minimalist"/"no frills" path toward learning DITA.

11

DITA Adoption TC

The DITA Adoption TC should address the perception that information typing (especially through DITA topic types) is not a hard requirement for learning or using DITA. That said, new users should be aware that ignoring information typing reduces the scope of what can be done in DITA (topic.dtd, basic maps).

12

DITA Adoption TC

The DITA Adoption TC should review the DITA maturity model (Priestley, Swope) as a framework for organizing and orienting the discussion about "what do I need to learn in DITA in order to achieve XXX or YYY or ZZZ goal?"

13

DITA TC

The DITA TC should develop a brief "reading guide to the DITA spec" that correlates features to usage/demographics. What's the learning path at each stage of the maturity model? How to move to the next level? (Organizations and individuals sometimes get stuck.) Individual TC members are encouraged to contribute rough draft material to the Adoption TC. Stan, Darryl, Kris, and Don have volunteered to help.

14

DITA Adoption TC

The DITA Adoption TC should add to the DITA XML site (http://dita.xml.org/resource-directory) an index of sample DITA files developed in support of the feature articles.

15

DITA TC

The DITA TC should for DITA 1.3 develop and review sample code snippets in the spec from the perspective of making them more easy to instantiate and process as working samples.

16

DITA TC

The DITA TC should add a requirement to the DITA 1.3 proposal development and review process about sample files. If feature advocates and champions can develop and make available working samples of proposed new features, that might go a long way toward making those new features testable and promotable. Generating feature-specific equivalents to the S1000D "bicycle" example would be great. Preserve the distinction between creating "sample files" to support learning and "test files" to address compliance.

17

DITA Adoption TC

The DITA Adoption TC should monitor the new-feature use case examples developed in the DITA TC to use as a foundation for DITA 1.3 feature articles.

18

DITA TC

The DITA-TC should explore opportunities for increasing the precision and/or usefulness of Google search results about DITA.

19

DITA-Adoption-TC

The DITA Adoption TC should explore opportunities for increasing the precision and/or usefulness of Google search results about DITA.

What do people mean when they say DITA is too complex?

People mean different things when they say that DITA is complex. In order to counter the impression that it is too complex, we must first understand who is getting that impression, and why. Different reasons will have different solutions.

Use this section to capture reasons that DITA may be seen as too complex. Please mark whether the statement is anecdotal, assumed, or otherwise; it is also helpful to mark what community is affected by this perception. For example - "Implementors of the standard may feel that it is too complex, due to the addition of industry-specific modules". Or, "Users have stated that DITA is too complex because they do not understand some of the features." Suggested solutions may also be included, preferably as sub-lists.

  1. DITA users have said that DITA is complex because it [ISSUE-01]] includes support for domains they do not need, and [ISSUE-02]] they do not know how to easily create new doctype shells. If we make it easier to subset the DITA DTDs [SOLUTION-01]], it only partly solves the problem. We'd also need to provide a way to easily subset the documentation [SOLUTION-02]].

    1. Could make Jarno's DTD/Schema shell generator widely available and officially supported [SOLUTION-03]].

    2. Could create default document types that include fewer domains (already done for "base topic") [SOLUTION-04]]

    3. Could create a set of constrained document types that remove some elements [SOLUTION-05]]

  2. DITA users have said that DITA is complex because it doesn't match their authoring domain. [ISSUE-03]]

    1. Could make specialization easier (new rules, new tools, aids to find a proper specialization match, etc) [SOLUTION-06]]

  3. DITA users have said that DITA is complex because it includes features / elements they do not use [ISSUE-04]]

    1. Could create a set of constrained document types with fewer elements and/or fewer features, directed towards a typical business user rather than a professional author [SOLUTION-07]]

  4. We believe DITA users have commented that specialization is too complex, because they do not know what specializations exist or how to dig through all the elements to decide what to specialize [ISSUE-05]]

    1. Could provide a repository for known specializations (this could be a final repository for products of DITA Subcommittees that are not put through the full standards process) [SOLUTION-08]]

    2. Could make specialization easier (new rules, new tools, aids to find a proper specialization match, etc) [SOLUTION-09]]

  5. Some DITA map concepts require an understanding of indirection and levels of abstraction that is often hard for the average writer to grasp. Relationship tables are one example. It's hard to see the value of reltables, unless you can understand the concept that the map drives the deliverable and abstracting related topics to the map makes sense in that context. Keys, key references, and content key references take that even deeper. [ISSUE-06]]

  6. Many new users' first experience with DITA consists of downloading the OT from Sourceforge and trying to get it to work. This is hard. [ISSUE-07]]

  7. We tell users to not create a new element or attribute type if there already is one in base DITA that serves the intended purpose. However, in order to find out whether base DITA already has one that serves the intended purpose, you have to do a lot of searching and reading. [ISSUE-08]]

  8. Users will believe something is simple when their peers say it is simple. However, there are few, if any, implementers saying that implementing DITA has been simple. [ISSUE-09]]

  9. There may be a widespread belief that DITA is about using task, concept, and reference topics, and that if your content doesn't fit into task/concept/reference or if you don't see the value in using typed topics, you aren't in DITA's league. [ISSUE-10]]

    1. This meme might come out of the common practice of starting introductions to DITA by decomposing the acronym, followed by an explanation of what "information typing" is. So information typing ends up being put front and center instead of other ideas such as conditional text and multi-lingual publishing.
  10. DITA users, trainers, and developers may find that the design of DITA itself sometimes provides multiple equally-prominent ways of doing things, in which no way is clearly the right one. For example, if you want to insert a submap into a DITA map, you can do it with either the <topicref> element or the <mapref> element. If you have an authoring tool which can set the @format attribute automatically, neither element is better than the other, so the fact that you have to choose makes life complex. The fact that <mapref> is not valid in DITA 1.1 also makes the decision complex. [ISSUE-11]]

[Stan Doherty, April 19 2011] -- At a DITA Adoption Help Subcommittee meeting (April 18), we discussed two substantive issues that we have heard from clients/colleagues in the past month:

  1. Feature usage/demographics: If 80% of DITA users actually deploy roughly 20% of the total DITA feature set (DITA-Lite), then 80% of what we talk about in our DITA 1.2 spec is either not relevant or not accessible to these folks [ISSUE-12]]. If the DITA TC and/or Adoption TC could profile and document which features are most often used by DITA-Lite people and which features needs to be there for enterprise implementers. This is basically a "reading guide" of some sort, not a formal subset DTD [SOLUTION-10]].

  2. Sample files: There is no library of ready-to-test DITA documents that clearly demonstrates DITA 1.0, DITA 1.1, and DITA 1.2 features. [ISSUE-13]]The code snippets in the spec are useful, but both tools vendors and basic DITA users would like to test live, certified-by-OASIS sample documents. Some people can work from the code samples in the spec to develop working documents and samples, many cannot [SOLUTION-11]].

    • [Adrian Warman, May 23 2011] -- Is there a case for distinguishing between Sample files and Test files? A set of test files would be used to ensure that an editor or build environment generates DITA-compliant output [ISSUE-15]. Sample files would be easy-to-read examples that bridge the gap between 'I want to do this' and 'this is how to do it'.

[Stan Doherty, January 18 2011] -- When I do demos and free consulting for groups in the Boston, I tend to interact with pubs managers and writers who are fairly technical and have attended introductory DITA training, but are not completely sold on DITA. When they voice concerns, here's what I hear.

I suspect that if we had an open-source, DITA-compliant editor to complement the open-source, DITA-compliant Open Toolkit, the folks with tool anxieties would have a common starting place for learning and piloting DITA [SOLUTION-12]]. If there were a shared and detailed learning path through DITA 1.2 features, the folks with overload anxieties would be happier. Pubs managers and writers do not have clear points of entry or engagement with the spec, so they are vulnerable to DITA critics who argue that investing time to figure it all out on their own is not worth the effort. If an alternative to DITA can do 25% of DITA in ways that small groups can implement confidently, that's better than failing to implement 0% of the complete DITA.

[Deb Bissantz, January 17, 2011] - From a tech writer perspective, there are too many pieces. [ISSUE-18]] There is the specification, there is the authoring tool, there is the publication tool, there is the open source toolkit, there are XSL transforms, there are FO processors, and most likely a content management system. The average writer doesn’t want to deal with all of these tools. Writers are spoiled with a single desktop publishing tool that has a WYSIWYG interface. There is no one tool yet that provides that seamless process from authoring to publishing.

The paradigm change from books to topics is a huge hurdle. [ISSUE-19]] Not being able to see how topics fit together is a difficult concept. Making the leap from a topic to final output is not obvious. I think many writers do not fully understanding the value of the map, especially all of the automated linking between topics.

[Tony Self, January 21, 2011] - When I encounter tech writers who have heard of DITA and have a negative view, they often ask me to re-explain it. They are sometimes confused by there being too much information, in a way. [ISSUE-20]] When they find some information via a Google search, it is probably not at the overview level, but at some deep, esoteric level. For example, they might Google for DITA, find an article on specialisation, read the first paragaph, and conclude that DITA is complex. If they are persistent, they might find a few more items. They might find the dita xml.org site, with a job ad and a 1.2 status article on the home page. They might find the OT site, and start confusing DITA with the OT. They might find a software tool site that allows you to create DITA documents without a knowledge of Java or XSL (presumably otherwise required). It's not surprising that those people conclude that DITA is complex and confusing.

There may be some critical mass issue as well. If they discuss DITA with other writers at a society meeting, will their own findings be reinforced by the equivalent experience of others? [ISSUE-21]] An explanation by someone who doesn't understand is bound to sound complicated or convoluted. At some point, when there are a number of DITA users at that society meeting, they are likely to get a better explanation of what DITA is.

In one of the online communities that I belong to, there are some tech writers with stridently anti-DITA views. [ISSUE-22]] Their views sometimes further muddy the water. For example, in one exchange in that community, it was claimed that to use DITA you need to be a programmer because you'll need to work with DTDs, XSL-FO, etc. The discussion developed to a point where advocate of DITA were painted as anti-writing. (If DITA users are programmers, and programmers make poor writers, DITA users are therefore poor writers.)

[Bruce Nevin 20110125] Some things are difficult to document in a succinct and easy-to-understand way, just in the nature of XML, until after the reader has turned some conceptual corners [ISSUE-23]] (separation of content from presentation; content that is inherently subject to reuse in contexts that cannot be foreseen; that is created and edited on the desktop but decidedly does not reside there; and so on). Lacking these fundamental understandings, the description of keyref and how the key space is established, for example, is difficult to motivate, much less to understand.

In 2.0 a re-thinking of the architecture will help in some areas [SOLUTION-13]]. A good example is in Eliot's suggestion in the "Publishing <topichead>" thread:

Discussion points

[S-L Yeo, January 11 2011]: When I did a Google search for "sample DITA specialization" today, I came across this as the second Google result: http://dita.xml.org/wiki/dita-specialization-by-example-pipeline. I have no idea what this is. [ISSUE-24]] Is this kind of thing, i.e. the often-confusing results that come up when you try to to search for basic information on DITA, part of the problem?

[Don Day, April 4 2011]: TMI in search results is always a problem for a deep subject. [ISSUE-25]] If Google could be hinted that the query is for a Novice role (just like we expect UI agents to do for role- or experience-based help), then perhaps we could make sure that certain novice-level topics rank higher in the hits [SOLUTION-14]].

There is often new-user confusion about the relationship of DITA with Information Mapping and S1000D. [ISSUE-26]] More clear positioning on the roles of each of those standards could be helpful [SOLUTION-15]].

ISSUE-to-SOLUTION MATRIX

ISSUE

PROPOSED SOLUTION(S)

STATUS

[ISSUE-1] DITA contains support for domains that users do not need.

[SOLUTION-1] DITA TC should make it easier to subset the DITA DTDs.
[SOLUTION-2] DITA TC should make it easier to subset the DITA documentation.
[SOLUTION-5] DITA TC should create a set of constrained document types that remove some elements.
[SJD-Update: The TC resolved to provide/identify an element "starter set."]

Status …

[ISSUE-2] DITA users do not need to know how to create new doctype shells easily.

[SOLUTION-3] DITA TC should make Jarno's DTD/Schema shell generator more widely available and officially supported.
[SOLUTION-4] DITA TC should create default document types that include fewer domains a la base topic.

Status …

Specializations and shells
[ISSUE-3] DITA does not match user authoring domains.
[ISSUE-5] DITA users believe that specialization is too complex.

[SOLUTION-6] DITA TC should make specialization easier (new rules, tools, auditing aids).
[SOLUTION-8] DITA TC should provide a repository of well-known specializations.
[SOLUTION-9] DITA TC should make specialization easier (new rules, new tools, new auditing tools).

Status …

[ISSUE-4] DITA includes features/elements that users do not use.

[SOLUTION-7] DITA TC should create a set of constrained document types with fewer elements and/or fewer features.

Status …

DITA Requires Conceptualization Changes
[ISSUE-6] DITA features such as maps, reltables, or keyrefs require a level of abstraction that many users do not have.
[ISSUE-19] DITA requires a paradigm change from books to topics that many users are unwilling or unable to make.
[ISSUE-23] DITA requires a conceptual foundation that may take more time to acquire than some users are willing to invest.

[SOLUTION-13] DITA TC should rethink some of the DITA architecture in DITA 2.0, e.g. abstract base classes.

Status …

[ISSUE-7] DITA users' first experience of DITA is a struggle with the DITA-OT.

-

Status …

[ISSUE-8] DITA users struggle with auditing existing elements/attributes before creating new ones.

[SOLUTION-16] DITA TC should improve documentation of attributes in the DITA specification. [SJD-Edit: The TC concluded that comprehensive coverage of DITA attributes comparable (perhaps) to coverage of elements would be beneficial to users. The priority here would be to make the DITA spec as strong as possible. Complementary efforts might include a separate, supplemental index to attributes developed by the Adoption TC??]

Status …

General Perception of Complexity
[ISSUE-9] DITA users hear from peers that DITA is too complex.
[ISSUE-11] DITA offers multiple, equally-prominent ways to achieve something.
[ISSUE-18] DITA involves too many pieces that a beginner must learn about and worry about.
[ISSUE-21] DITA lacks a critical mass of successful users attending the user groups and conferences where beginners form their opinions about DITA.

-

Status …

[ISSUE-10] DITA users perceive information typing as a prerequisite to using DITA; if typing is not obvious to them, they balk.

-

Status …

Usage Patterns and Learning
[ISSUE-12] DITA feature usage demographics is not formally documented.
[ISSUE-17] DITA offers no formal learning path through its features for beginners, novices, and experts.

[SOLUTION-10] DITA TC and/or Adoption TC should publish a brief "reading guide to DITA spec" that correlates features to usage/demographics.

Status …

[ISSUE-13] DITA publicizes no set of robust, ready-to-test sample files that illustrate all the current features.

[SOLUTION-11] DITA TC should create a library of OASIS-certified sample files that are correlated to DITA features.

Status …

[ISSUE-14] DITA is increasingly optimized for consultants, architects, and tools developers.

-

Status …

[ISSUE-15] DITA is not associated with the authoring tools that people have been using for 20+ years.

-

Status …

[ISSUE-16] DITA may not be a solution for small groups, especially those without budgets.

-

Status …

[ISSUE-20] DITA publications, web sites, and search results are voluminous and somewhat contradictory.
[ISSUE-24] DITA search results on topics such as specialization are often confusing.
[ISSUE-25] DITA search results do not give users much of a clue about content difficulty (beginner, novice, expert).

-

Status …

[ISSUE-22] DITA has its strident critics; some of their criticisms go unanswered by the DITA community.

[SOLUTION-14] DITA TC should figure out how to have Google query results provide hints about topic complexity.

Status …

[ISSUE-26] DITA is easily confused with Information Mapping and S1000D.

[SOLUTION-15] DITA TC should clarify the positioning of DITA relative to Information Mapping and S100D.

Status …

PROPOSED SOLUTIONS

[SOLUTION-1] DITA TC should make it easier to subset the DITA DTDs.

[SOLUTION-2] DITA TC should make it easier to subset the DITA documentation.

[SOLUTION-3] DITA TC should make Jarno's DTD/Schema shell generator more widely available and officially supported.

[SOLUTION-4] DITA TC should create default document types that include fewer domains a la base topic.

[SOLUTION-5] DITA TC should create a set of constrained document types that remove some elements.

[SOLUTION-6] DITA TC should make specialization easier (new rules, tools, auditing aids).

[SOLUTION-7] DITA TC should create a set of constrained document types with fewer elements and/or fewer features.

[SOLUTION-8] DITA TC should provide a repository of well-known specializations.

[SOLUTION-9] DITA TC should make specialization easier (new rules, new tools, new auditing tools).

[SOLUTION-10] DITA TC and/or Adoption TC should publish a brief "reading guide to DITA spec" that correlates features to usage/demographics.

[SOLUTION-11] DITA TC should create a library of OASIS-certified sample files that are correlated to DITA features.

[SOLUTION-12] DITA TC should encourage someone to develop a very basic open-source, DITA-compliant editor.

[SOLUTION-13] DITA TC should rethink some of the DITA architecture in DITA 2.0, e.g. abstract base classes.

[SOLUTION-14] DITA TC should figure out how to have Google query results provide hints about topic complexity.

[SOLUTION-15] DITA TC should clarify the positioning of DITA relative to Information Mapping and S100D.

[SOLUTION-16] DITA TC should improve documentation of attributes in the DITA specification.

DITA_Perceptions (last edited 2011-06-15 14:47:40 by StanDoherty)