OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-adoption message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [dita-adoption] DITA backlash


Hi David and Rodolfo,
Part of the problem is clearly information architecture. Because of some of the notions we have carried forward from the textbook world, we continue to impose multiple levels of hierarchy onto technical documents. As a result, writers create topics that have no content simply to group other topics under a heading--lingering effects of chapter structures. More than 20 years ago, when Ginny Redish and I helped design a new information architecture for Hewlett-Packard, we wrote in the writer guidelines to flatten the structure. Was it really necessary to have a topic called "Removing and Replacing the Cabinet" followed immediately by two child topics, "Removing the Cabinet" and "Replacing the Cabinet"? 

In more than one contextual inquiry we did at customer sites, we heard from customers that they hated landing on these useful topics that had titles and no content. They were searching for something specific and wanted that, not empty content. In one truly unfortunate implementation, the system provided no path from the found topic to the children topics. You never knew where you had landed. That made the customers even more furious. One gentleman shouted to us: "This is useless!!"

DITA has provided mechanisms that allow writers to happily recreate 60s style content. We should stop doing that. Let's get rid of the unnecessary nesting of content and flatten the structure. All these silly problems would go away (or at least that's my hope). Of course, this recommendation has most to do with basic writing principles and nothing to do with DITA.

JoAnn

JoAnn T. Hackos, PhD
President
Comtech Services Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
joann.hackos@comtech-serv.com
skype joannhackos





-----Original Message-----
From: dita-adoption@lists.oasis-open.org [mailto:dita-adoption@lists.oasis-open.org] On Behalf Of Rodolfo M. Raya
Sent: Wednesday, August 29, 2012 10:08 AM
To: 'DITA Adoption TC'
Subject: RE: [dita-adoption] DITA backlash

Hi David,

Your comments are valid, DITA can be confusing for a starter. It happened to me, so I decided to buy a book and ask for help. Both approaches were useful.

There are good books for learning DITA. IMHO, That should be the first thing to look for when starting.

Regards,
Rodolfo
--
Rodolfo M. Raya       rmraya@maxprograms.com
Maxprograms       http://www.maxprograms.com

> -----Original Message-----
> From: dita-adoption@lists.oasis-open.org
[mailto:dita-adoption@lists.oasis-
> open.org] On Behalf Of David J. B. Hollis
> Sent: Wednesday, August 29, 2012 12:58 PM
> To: DITA Adoption TC
> Subject: Re: [dita-adoption] DITA backlash
> 
> 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-arch
> > it
> > ecture.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)
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-adoption-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: 
> dita-adoption-help@lists.oasis-open.org



---------------------------------------------------------------------
To unsubscribe, e-mail: dita-adoption-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: dita-adoption-help@lists.oasis-open.org



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]