Everything Else is not a Concept

By | 2012/08/20

In any system that attempts to classify the whole of something, there is usually a category that essentially constitutes “everything else”. In the terrible troika of task, concept, and reference, that role belongs to “concept”.  In Tom Johnson’s shapes of help graphic, which have quoted before, and repeat here, task has the shape of a procedure, reference the shape of a table, and concept the shape of plain text.

Tom Johnson's "Shapes of Help" graphic.

Tom Johnson’s “Shapes of Help” graphic.

Concept, then, stands for the plain, the generic, the featureless and structure-less.

But is that all there is to structured writing: tasks, references, and everything else? To be sure, every structured writing system needs some kind of generic topic structure, for a few reasons:

  • There will genuinely be some topics that are merely discursive narratives and have no particular internal structure at all.
  • You will sometimes have topics that could certainly have a structure applied to them, but you don’t have enough of them to justify creating a separate type for them.
  • You will sometimes have topics for which you know you will want to develop and enforce a structure, but for which you don’t yet have enough information to develop that structure, and you need a place to capture them in the meanwhile.

Okay, but what does it matter what you call that class of topics? What difference does it make if you call such topics “generic” or “concept”?

It makes a difference in a number of ways.


Dividing content into tasks, references, and concepts, is like dividing the animal kingdom into cats …

First, saying “generic” reminds you that you are not giving a topic a real type at all, but recognizing that it has no type. Calling it a “concept” makes it sound like you are actually giving it a type (one of the three canonical types: task, concept, and reference), and that can lead you to think your information typing job is done. Generic makes you ask if the topic is really generic, or if you should be doing more to define its type; concept raises no such questions.

Second, “concept” is one of the slipperiest words in the English language. In some general sense, it means a thought or an idea, but, as the Wikipedia article on Concept succinctly begins: “The word concept is defined variously by different sources.” Its full meaning has vexed philosophers for centuries. Its multiplicity of meanings is perhaps what made it a candidate for the third member of the troika, since there is probably some meaning of the word “concept” that can be applied to any text. But you do not want a category name to work because it is ambiguous. You do not one some members of the category qualifying under one meaning of the term and some under another. Categorization only tells you something useful about the things it categorizes if the categories are clear and unambiguous.

Third, one of the many meanings of “concept” is actually relevant to a great many technology products. Many products are designed around certain fundamental ideas, which the user needs to understand in order to get full use of the product. If the user is switching from one technology to another (such as switching from an unstructured desktop publishing process to a structured writing process), it will be particularly important for them to grasp the fundamental concepts of the new technology, and how they differ from those of the old. In this sense, a concept is not “everything else” but something quite specific. But if the user is presented with hundreds of hundreds of topics labeled “Concept”, these essential foundational  concepts can be lost in the noise.


… dogs, …

Fourth, there are plenty of topic types that are not, by any reasonable definition of the words, either tasks or references, and which are not concepts in the sense described above. Nor are they generic. An example from my own background writing about programming languages and operating systems, is the annotated code sample topic.

Programmers basically want two things in a documentation set: an API reference and code samples. Programming task topics may be useful, and in some cases programmers would really benefit from paying some attention to the fundamental concepts of the language or OS, which may be quite different from those they are used to (markup processing languages like XSLT can be very confusing to regularly trained programmers, who often use them wrong because they don’t understand them) — but what programmers want, universally, is an API reference and code samples.

The documentation’s best chance of educating a programmer of the fundamentals of how a language or and OS works is through well-documented code samples. That merits a topic type in its own right. And code sample topics do have a definite structure to them. There are a number of things that every code sample topic should include, starting, of course, with the sample code itself and its annotations, and including such information as the versions of the API supported, the language of the sample, the resources it requires, and, in the case of specialty applications, such as embedded or real-time systems, its security and performance characteristics, and other product or craft-specific information. I’m sure similar examples will spring easily to mind for those in other fields.

Another example is something I regard as particularly important in any topic-based information set: pathfinder topics. Pathfinder topics are not task topics (in particular, they are not the same thing as workflow topics, which are a kind of task topic). Nor are they big-C concept topics. Rather, they are topics that help the user find their way around the technology, giving them a sense of where everything is and how it works together to achieve the user’s ends. If big-C concept topics are aimed at understanding, pathfinder topics are aimed at orientation and planning. Pathfinder topics are a topic type in their own right.

.. and everything else.

There are, then, besides the truly generic, many kinds of specific topic types, one of which, in a very specific sense, is concept. Concept is not the right word to describe “everything else”, nor is it useful to single out tasks and references as particular types and then assign everything else to a single category, however named. To do so is akin to dividing the animal kingdom into cats, dogs, and everything else.

We need to free ourselves from the tyranny of the terrible troika and develop an appreciation for the many different types of topics that are needed in a structured writing environment. It we want to apply real and useful structure to the topics we create, we need something more than the simplistic trio of concept, task, and reference.
Photos: FreeDigitalPhotos.net


Series Navigation << A Task is Not a Procedure<< A Reference is Not a TopicWe Must Develop Topic-Based Information Design >>

6 thoughts on “Everything Else is not a Concept

  1. Thomas Kohn

    OK, you’ve convinced me. Though I’ve long considered “Concept” to roughly equate to “Narrative,” you do well describe some alternative topic types as fundamentals to user information.

    So is the next step to talk about specializations or to lobby OASIS for changes to their toolkit?

    1. Mark Baker Post author

      Thanks for the comment, Thomas. The next step, I guess, depends on whether you are constrained to stick with DITA or not. DITA has a fundamental problem with true topic typing because it uses “topics” both as an element of information design and as an element of reuse. While you could use maps in DITA to construct Every Page is Page One topics out of multiple reusable content chunk topics, there is no topic typing in maps, so you get to topic type definition or support when you do this.

      You could also write Every Page is Page One topics as single DITA topics, and use specialization as a means to at least somewhat define a proper topic type (specialization is a very weak topic typing mechanism compared to plain vanilla XML Schemas or DTDs). But then, of course, you compromise you ability to use the central reuse mechanism in DITA.

      Either way, DITA is seriously compromised by the failure to provide separate mechanism for true topic typing and for reuse. This is why in SPFE/EPPO-simple, the topic is purely a unit of information design, and fragments and text objects are provided as units of reusable text.

  2. Ruth

    I appreciate this series on topic structure. Due to lack of chunking support in tools I’ve used, I have started to abandon topic typing and moved to an all-concept model – otherwise HTML output has too little content per page, which is an impediment to readers – and I don’t compromise my readers in favor of ideology.

    I wrote about this issue here: http://focusonreaders.blogspot.ca/2012/07/case-study-dita-topic-architecture.html

    But reading your posts has made me question that move… not that I have a solution yet.

    I have a quibble with what you said about developer documentation. Devs need and want more than API refs and code samples, and it impedes navigation to bury performance or security details in code sample topics. I have spent a lot of time at developer conferences doing doc usabilty studies, so I’m not just blowing smoke. They definitely want good, beefy API refs and lots of code samples and snippets, but they also want and need overview information, best practices, UI guidelines, security implementation, performance considerations, integration with third party technology, etc etc.

    1. Mark Baker Post author

      Thanks for the comment Ruth. I don’t disagree with anything you say about developer documentation. I would say that API refs and code samples are the core things that all devs want, regardless of circumstances, but that all the other things you mention are also important to different extents for different types of APIs or operating systems. APIs and samples are always necessary, but not always sufficient.

      I also agree the security and performance information cannot be contained only in code samples. Where such issues exist, they must be treated as a first class subject in their own right as well. But where a code sample has security or performance implications, they must be mentioned in the documentation of the code sample (with links to the first class security and performance topics as well). We don’t control the vector a developer takes through the documentation, so we must cover all the pertinent points, at least by reference, in every pertinent topic — Every Page is Page One. One of the main uses of formal topic typing to to remind us to do this.

      I love your blog post. The DITA chunking mechanism strikes me as a band-aid on broken leg — a mechanism totally inadequate to fix the problem that DITA created by failing to separate topic as a unit of information design from topic as a unit of reuse. It becomes increasingly clear that this failure is leading to information design nightmares and the creation of the kind of Frakenbooks you describe.

  3. Myron Porter

    Much appreciation for explicating what has been nagging at the back of my mind for a few years: the underlying philosophy, at least, as frequently presented.

    While a deconstructionist approach may work with experimental novels and films–e.g. Robbe-Grillet–it is not an ideal candidate for technical documentation. Blind acceptance of any paradigm serves no one. Only by understanding, working through a paradigm, and mapping its true usefulness, application and blind spots can we hope to effectively harness its power. Again, much appreciation for having done the hard work.

  4. Mark Baker Post author

    Hi Myron. Thanks for the comment. Much hard work remains to do, I think.


Leave a Reply