Problem of redundant content in the DITA 1.2 spec

[Kristen James Eberlein <kris@eberleinconsulting.com>]

As I mentioned in today's TC meeting, Michael Priestley raised a vital point in his 3rd draft review of "Introduction to DITA" > Basic concepts. I'll copy and paste the discussion here:

Basic concepts

In progress

[MPriestley 17 December 2009] Most of these topics are redundant with ones later in the spec, especially under Processing. In the 1.1 spec, there was no redundancy - the "basic concepts" section simply linked to overviews distributed across the arch. Now that we have these redundant sections, it's a lot harder to see how the sections relate, and we have the same info expressed in different ways in different parts of the spec.

---

[Hamilton 4 Jan 2010] Michael makes a good point here, though I do think it's nice to have a place to go to get oriented. If you do keep these topics, they should at least point to the related information in other sections.

---

[Eberlein, 12 January 2010] Michael, you make an excellent point. I wish that this issue had been raised earlier; I don't think that the original writers (mine is the 3rd set of hands that has been on these topics) were aware of the logic behind the architectural strategy in the DITA 1.1 spec. Also, the problem of duplication has been further aggravated by our team authoring approach.

From my point of view, we must avoid unnecessary duplication of material; it is antithetical to the principles of modularity and single sourcing which are underpinnings of DITA. (It also impedes maintenance and significantly raises the likelihood of inconsistency.)

Off of the topic of my head, I see the following options:

• Return to the architectural strategy employed in the DITA 1.1 spec, where the "Introduction to DITA" section simply contained cross references to core conceptual topics, accompanied by conrefed short descriptions from the topics
• Have the other sections of the spec contain the cross references and conrefed short descriptions to the core conceptual topics, which remain located in the "Introduction to DITA" section

If there's any other possibilities, I'm not seeing them. Which route we take might need to be driven by which will require the least work.

Either strategy is going to require (at least) the following work:

• Identifying where topics overlap
• Consolidating overlapping material into a single topic or single topic collection

I'm going to create a Wiki page and start identifying the areas of overlap: Content duplication problem


Best,

Kris

Kristen James Eberlein
Principal consultant, Eberlein Consulting
Secretary, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
www.eberleinconsulting.com
http://www.linkedin.com/in/kristeneberlein
+1 919 682-2290; keberlein (skype)