Topic types
by Marcia Poulsen, member, Central New York chapter and Online SIG
The feedback I’ve received on my presentation, originally posted on this site Aug. 5, has inspired me to revise it. The updated version is entitled “The Three Core Topic Types: Concept, Task, Reference” (PPT, 4.5 MB).
Thanks to all who contributed thoughts.
August 25th, 2006 at 1:27 pm
With Neil Perlin’s permission, I’m sharing here a comment he e-mailed on Aug. 25:
“Your three topic types are a good starting point, but I lean toward adding types as needed instead of shoe-horning everything into a few fixed types…. After a while the debate becomes pointless. I tend to go with concept, task, reference, and troubleshooting for primary types, with types like Show-Me and process as needed. Again, in a nutshell, I go with the ‘keep it simple and consistent’ approach.”
My thoughts in response:
I didn’t realize what controversy I was stepping into when I started exploring this subject! It’s been fascinating to me the various topic types that people have told me they use. Typically people say “We use concept, task, reference, and ______________,” as if to contradict the notion of having three core types.
But interpreting the three core types broadly as I do, I don’t see those “additional” types as fourth (or seventh) core types as much as variations on the three core types, without any shoe-horning required.
Theoretically, someone could come up with a type that can’t be construed as a variation on the three. Even DITA allows for this possibility, since its three “out of the box” core types are based on (are specializations of) the stripped-down type simply called “topic.” In the end, as you say, the debate becomes pointless.
There is value in having a starting point, and these three core types are universal enough to constitute a common starting point. From here, people can define (refine, customize, specialize, create) their own working set of types. For any particular context, it’s irrelevant whether the customized types (such as troubleshooting or Show Me or process) are considered variations on a core type or simply additional types.
Thanks, Neil. I’d be interested to hear others’ comments on this line of thinking too.
January 29th, 2007 at 8:22 am
At FarPoint Technologies, where I work, we use a custom DTD that has, at its basis, the same idea of the three types and find that everything fits into those three just fine. Our DTD is much smaller but can easily map to DITA as needed if we ever needed to share our documentation in XML with another partnering organization. While DITA is good for the industry, it’s not the only solution and not always the best within a company; custom DTDs are often the best solution, but the three topic types, I think, are universal. I agree with Marcia that, at least for software product documentation, every other type is a subset of those three types.
May 18th, 2007 at 12:49 pm
Hi Marcia and all,
I am trying to locate the origin of concept, task, and reference as the three basic information types.
Does anyone have any specific sources of this idea?
Thanks,
Bob.
May 21st, 2007 at 7:14 am
This is a great question. I’d love to know the answer myself. These basic information types surely predate JoAnn Hackos’s classic book “Standards for Online Communication,” which came out in 1997. She identifies these types there but doesn’t attribute any source to them.
May 21st, 2007 at 8:11 am
DITA was originally developed by IBM, so I would go back to them or to the Oasis Site to find the origins of the terminology. I’m not seeing the answer directly in a quick scan, but it may be somewhere on one of the pages.
You could also contact Michael Priestly directly. He is one of the IBM engineers who helped develop it; his email is on the IBM pages.
http://www-128.ibm.com/developerworks/xml/library/x-dita1/
http://www-128.ibm.com/developerworks/xml/library/x-dita3/index.html
http://www.oasis-open.org/committees/dita/faq.php
Regards,
Carla
***************************************
Carla Martinek, Senior Translation Coordinator/Editor
Zebra Technologies Corporation
May 21st, 2007 at 8:49 am
Char James-Tanny added this (in the STC Single Sourcing SIG listserv):
One of the earliest places I saw these terms defined (loosely) was in
“Developing Online Help for Windows” by Scott Boggan, David Farkas, and Joe
Welinske, published in 1993. At that time, topic types were “procedure” and
“command”. More comprehensive definitions were available in Cheryl Lockett
Zubak and Mary Deaton’s book, “Designing Windows 95 Help: A Guide to
Creating Online Documents”, published in 1996.
May 21st, 2007 at 9:44 am
Zev Frutkoff, Jerusalem, Israel, added this (in the STC Single Sourcing SIG listserv):
DITA types are based on the information typing developed by Robert E. Horn back in the 1970s. Horn later founded Information Mapping Inc. (www.infomap.com) to teach his methodology.
Horn defined seven information types; “concept” was one of them. What DITA calls a “task”, Horn called a “procedure”. The DITA “reference” most nearly matches Horn’s “structure”. The remaining four types (classification, process, principle, and fact) were dropped by the designers of DITA, probably because they don’t have much use in software or hardware documentation.
May 21st, 2007 at 12:05 pm
Scott Wolff, consultant, added this (in the STC Single Sourcing SIG listserv):
Information Mapping does bear certain similarities, but because it predates
the use of DITA and XML by decades, there are important differences.
The DITA model architecture builds on “topics” while Information Mapping
utilizes “blocks and maps”. It may seem that perhaps blocks are topics, and Information Maps are DITA maps, but in practice, if you are a strict
practitioner of Information Mapping, these generalizations do not hold.
Sometimes Information Maps are topics, sometimes DITA Maps, similarly,
Blocks are may be represented a topic, sometimes as content units within
topics. It is important to establish how Information Mapping principles and
types will be applied if you choose to implement using DITA.
Additionally, DITA, which is an XML vocabulary, separates the
content/structure from the presentation. Since Information Mapping predated wide spread adoption of markup languages, it makes no such distinction.
Finally, DITA does not remove types so much as it generalizes on what types are. For example, Concept under DITA is anything “conceptual” while Concept under Information Mapping is a “definition”. Most new users find it easier to apply DITA than Information Mapping as it reduces the choices to the three main information types as opposed to the seven defined under the original work by Horn.
May 21st, 2007 at 3:44 pm
Paul Neshamkin added this (in the STC Single Sourcing SIG listserv):
Microsoft started talking about topic types in 1994-95 in their guidelines
for authors writing for WinHelp 40 (Windows 95/NT Help). The topic types
mentioned were conceptual, procedural, and What’s This.
We had started talking about the topic type concept [Marcia’s note: I think he means “topic type idea”] at Wextech (creators of Doc-To-Help, the original Help authoring tool) as early as 1992-3. We rolled reference and overview into “conceptual,” and of we called tasks “procedures,” so we were already using “procedural” as our other topic type. God knows where we got these terms from.
Regards,
Paul Neshamkin
pauln@helpauthors.com
MS Help MVP
ComponentOne Doc-To-Help Certified Trainer and MVP
WexTech MVP, and Certified Trainer
The Paul Neshamkin Group
http://www.helpauthors.com
201-714-9525
May 22nd, 2007 at 6:39 pm
Perhaps try some references in Ruth Clark’s (www.ClarkTraining.com) book – Developing Technical Training. In this book, she briefly outlines the literature that has led her to the information types she uses for technical training. She essentially uses tasks (procedures), concepts, and reference (facts), as well as two other information types. The authors of interest are essentially Bloom, Gagne, and M. David Merrill. She has also been influenced strongly by Horn and Information Mapping.
It seems that the information types keep coming up over and over. In Hackos’ “Standards for Online Communication,” chapter 4 talks about information types. She has a small bibliography that doesn’t look like it answers Bob’s question, but through the bibliographies in those books he may be able to get on the path to an answer.
Hope this helps,
Alan
May 22nd, 2007 at 8:03 pm
Bob Doyle added this (in the STC Single Sourcing SIG listserv):
I want to thank everyone for their suggestions as to the origin of concept, task, and reference.
The only places I find these three consistently together are in work from IBM, including DITA itself, and in the book Developing Quality Technical Information, by Gretchen Hargis et al, which nowhere mentions DITA.
As Zev mentioned, Information Mapping was the first to define “Information Types” in their methodolgy for Structured Writing. I find the differences between IBM and Information Mapping types to be so great that the IBMers probably did not even know the earlier work. Or if they did, they blatantly ripped off Horn’s terminology without attribution.
Someone from the DITA design team should be able to clarify this history for us.
I think I see in the three information types - concept, task, and reference - a reflection of the three great user manuals of the golden age of software documentation, when some of us still read manuals in order.
In 1984 Apple called them, for example, Learning MacPaint, Using MacPaint and MacPaint Reference.
My first tech docs were the user manuals for my MacPublisher (the first DTP program), which shipped in the year of the Mac, in English, French, German, and Italian.
To this day, many O’Reilly books follow the triad of Learning PHP, Programming PHP, and PHP - the Definitive Reference.
I think the “Learning X” manual has just disappeared. It is now seen as too much theory, overview, and system description. For many software products, you now have only Getting Started and Using X.
John Carroll’s “minimalism” moved the primary documentation focus to the practical “how-to” kind of knowledge we discover by user and task analysis. In his book 1990 Nurnberg Funnel (p.7), Carroll defined minimalism as “allowing learners to start immediately on meaningfullly realistic tasks.” Today’s impatient users are not so interested in learning the theory and overview, they want the instant gratification of problem solutions.
So I see “task” as the primary topic type. It has always been the main type in our Help Authoring Tools. I see concept and reference as supporting task, but only as needed.
This helps me to understand what is expected in the concept and reference topic types.