dita-adoption message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [dita-adoption] DITA backlash
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: JoAnn Hackos <joann.hackos@comtech-serv.com>
- Date: Wed, 29 Aug 2012 13:24:23 -0400
I think overview/container topics provide
a valuable service in an online navigation system. They may be empty when
authored, but they get filled with links to the children topics, so to
some degree act as an auto-summary of closely related material. I think
they are particularly useful when the documentation is reflecting a hierarchical
task analysis (HTA).
But I think that's a side issue for
the original case study cited below. In the specific example provided
by the case study, they should simply have collapsed the concept into the
task context section, and the separate sample topic into the task example
section. But she'd already decided not to use task, but jam everything
into concept instead.
The other article she cites makes a
similar judgement on the chunking levels of DITA, and based on a similar
misunderstanding: that DITA topics are the same as Infomapping blocks,
and that therefore a DITA task is no more than a single set of steps (no
context, no prereqs, no result, no example...), and that therefore DITA
content is incomplete.
In fact there is plenty of room in the
existing DITA content model for both small chunking and large chunking
approaches, as appropriate to the type and complexity of material.
Michael Priestley, Senior Technical Staff Member (STSM)
Total Information Experience (TIE) Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
From:
JoAnn Hackos <joann.hackos@comtech-serv.com>
To:
"Rodolfo M. Raya"
<rmraya@maxprograms.com>, "'DITA Adoption TC'" <dita-adoption@lists.oasis-open.org>,
Date:
08/29/2012 12:21 PM
Subject:
RE: [dita-adoption]
DITA backlash
Sent by:
<dita-adoption@lists.oasis-open.org>
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
---------------------------------------------------------------------
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]