Re: [dita-adoption] DITA backlash

["David J. B. Hollis" <dhollis@AandOConsultancy.ltd.uk>]

Hi All,

OK, so someone is new to DITA. They have a basic understanding of  
topics, and the DITA structure. They know their company's products and  
customers well, and know what topics are required. So they have an  
idea of the concepts, tasks and supporting reference material.

Great!

Then they find that they need to organise those topics into a  
hierarchy. A series of main and subtitles, chapter headings and sub  
headings.

They're then faced with a dilemna:

1. A whole bunch of 'silly' single paragraph, perhaps, topics that are  
mainly there to carry a title.

2. Introducing topicheads with navtitles and possibly shortdesc into  
the map.

The former seems to be a waste of a topic and bumps up the file count.  
The latter means putting content into the map, which somehow seems to  
be wrong, or at least peculiar. It would probably be difficult to  
reuse that content, if that were required.

First, what would be 'DITA best practice'?

Second, is there anything to guide a newbie? A simple primer on  
topics, or the DITA architecture? Some best practice examples?

The obvious starting point is the Toolkit. I've just looked at the  
samples folder. There are two overview topics that have no more than a  
title and shortdesc in them, used in hierarchy.ditamap. Examples of 1.  
above.

Apologies if I seem to be stirring. That is most definitley not the  
intention. I'm just trying to read between the lines, and trying to  
see if there is a possible underlying issue that needs to be addressed.

I might also have completely missed the point, as I tend to work with  
PDFs rather than HTML. If so, many apologies.

HTH,
David


> I hate to say it, but I have long suspected that many implementers  
> of DITA don't know what they're doing when it comes to information  
> architectures and output shaping. Myself, I've yet to work on a DITA  
> project that did not output multiple topic types in HTML. Why not?  
> <dita> wrappers and dita maps with chunking are obvious mechanisms.
>
> Yet, I have to agree with the poster in that I've also seen some  
> truly bizarre "architectures" using DITA.
>
> DITA is like a kitchen knife. You can use a chef's knife to create a  
> culinary masterpiece or you can use to commit murder. Unfortunately,  
> murder is easier.
>
> Troy
>
> -----Original Message-----
> From: Kristen James Eberlein [mailto:kris@eberleinconsulting.com]
> Sent: Monday, August 27, 2012 3:21 PM
> To: dita-adoption@lists.oasis-open.org
> Subject: [dita-adoption] DITA backlash
>
> http://focusonreaders.blogspot.ca/2012/07/case-study-dita-topic-architecture.html
>
> Joann, you should recognize this author as someone who garnered  
> quite a lot of attention on LinkedIn recently ...
>
> --
> Best,
>
> Kris
>
> Kristen James Eberlein
> Principal consultant, Eberlein Consulting Co-chair, OASIS DITA  
> Technical Committee Charter member, OASIS DITA Adoption Committee www.eberleinconsulting.com
> +1 919 682-2290; kriseberlein (skype)