dita — archive

[Kristen Eberlein]

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)