The distinction between concepts and reference topics is much easier and clearer when both support strong and clear task topics.
Concept or reference?
One of the recurring difficulties when moving to structured writing and topic-based authoring is the distinction of topic types concept and reference. It’s an odd problem because the three topic types, concept, task and reference seem rather logical and clear-cut in theory.
I’ve found that the best remedy for the confusion is the motivation that lies beneath topic-based authoring: Task orientation. Think of it this way:
- Task orientation is a design strategy for your documentation
- Topic-based authoring is “only” the method to implement task orientation.
So concept topics and reference topics exist to support tasks. “The goal for users … is not to understand a concept but to complete a task.” (p. 41, DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA).
Let tasks lead the way
Much of the uncertainty whether a topic is a concept or a reference disappears, when you have strong, solid task topics in place. Topics that directly address your users and their daily tasks and help them to get their job done:
- How do I create cool espresso drinks with my new coffee machine?
- How do I clean the milk steamer?
Such tasks are the context in which the two definitions of concept and reference from the DITA 1.2 specification make sense:
- Concepts “provide conceptual information to support the performance of tasks”.
- Reference topics “provide for the separation of fact-based information from concepts and tasks”
Note that both definition recur to tasks, so task-orientation and tasks as above are at the heart of topic-based authoring.
To help readers understand the background to tasks, you can offer concepts about the kinds of espresso drinks there are and how they differ.
To support users to actually perform the tasks, you can offer reference topics with technical specifications such as required voltage and recommended water softness.
How to distinguish them?
If you’re in doubt in particular examples, maybe the table below can help you. I got some of the criteria from a Yahoo group discussion “Concept v Reference – Battle to the Death” and from a blog post on Dubious Prospects.
| Concept topics | Reference topics |
| Are abstract ideas | Are specific settings |
| Explain meaning or benefit | Give facts without much explanation |
| Can stay when specifications change | Change with specifications |
| Support understanding of tasks | Support correct execution of tasks |
| Are read for background information | Are read for detailed information |
| “Why brushing your teeth is important” | “Stages of tooth decay” |
Filed under: DITA, structured writing, topic-based authoring |
Kai's Tech Writing Blog 
You’re absolutely right, Kai, when you say that the key to understanding concept and reference topics is in understanding that they exist to support task topics.
Here’s a rule of thumb to add to your “How to distinguish” list: If the reader will refer to a topic once or twice, in order to grasp an idea, it’s probably a concept topic. Conversely, if the reader will refer to a topic again and again, for example to check the valid values for a setting, it’s probably a reference topic.
Good point, thanks, Larry. I agree, frequency of use would apply in the context of the other criteria. Taken by itself, it’s maybe less useful since there seem to be an awful lot of reference topics which I don’t refer to more than once or twice, so that distinction seems weaker than the other criteria…?
Interesting. I did not know this was a point of contention, but it does seem to confirm something I have long felt about the DITA troika, which is that reference is not a topic type but a database.
Describing a reference as fact-based doesn’t get you anywhere: one hopes all of the documentation is fact based. What distinguishes a reference is not that it contains facts, but that it contains facts on parade, facts ordered by rank and file so that you can locate the single fact of current interest more efficiently.
The defining characteristic of a reference is that it involves a reliable lookup based on multiple points of data. Reliable, in this case, means that you don’t have to look at every data point to be sure you have the right one.
In print, a table is the classic format for a reference. It provides for a two value lookup by column and row, and assures you that if you have the right column and row, you don’t have to look at every cell of the table.
The problem with table is:
* They don’t support a lookup based on more than two metadata fields (or, at least, not well).
* They don’t work well on small devices.
There are much better ways of providing reliable multi-value lookups on an online platform. But to be able to provide interactive lookups, rather than tables, you have to store your content in a database, not a topic.
Thanks, Mark, well put. We have a lot of reference information, and we’re starting to find that presenting it clearly and consistently presents problems of its own.
As we’re moving towards structure, we’re focusing on getting topics and their types right for now, even if it means coping with reference tables for the time being. Fortunately, we can rule out the mobile issue, since our software product is even less suitable for small devices than our documentation.
Your idea of a reference DB will be a helpful scenario for the future, when we’re ready to take the next steps!
(Nice post, Kai. It makes so many things clearer to re-focus on tasks, or even better, user goals.)
I wanted to follow up on this thought-provoking reply from Mark. I do think it would be great to provide better ways of looking up reference information. But I’m not sure that there’s always a “single fact of current interest”. Sometimes reference items are read in relation to each other, for example where you have a short list of related settings and you need to figure out how they work together.
Perhaps a useful reference lookup experience would be to search for an item, and get a page with the searched item highlighted, but with closely related items also displayed to provide context.
One more thought regarding improving reference content on mobile within a standard DITA implementation and publishing pipeline — where there’s a simple table of terms/descriptions, it may help to tag this as a definition list. That’s easily formatted as a table in PDF and large screen online contexts, but as headings and descriptive paragraphs for small screens.
Great article, Kai. It definitely echos a mantra I’ve been stating for year. Write the tasks first and then look for what’s needed to complete the task. Anything that has to clarify underlying ideas about the task are concepts. Information that may be needed to complete the task, like values, are reference topics.
A great summation. Thanks for sharing.
Thanks, Julio! Ah, shoulda asked you in the first place… 🙂 But then, such conceptual misunderstandings are hard to predict.
The problem hadn’t occurred to me, since I focus most of my documentation around tasks. It was only when I saw how one writer with a lot of reference information was undecided whether to make his content reference or concepts that the issue popped up – and then it proved to be easiest to solve it by taking a step back and remember task orientation.
Hey Julio, thanks for the AMAZING explanation: Write the tasks first and then look for what’s needed to complete the task. Anything that has to clarify underlying ideas about the task are concepts. Information that may be needed to complete the task, like values, are reference topics. Don’t need to read anything more 🙂
Great post, Kai! This is always a sticking point with writers who are new to topic-based writing.
One place where I differed from you is that I would be tempted to write a topic that describes “the kinds of espresso drinks there are and how they differ” as a reference topic. For me, an analogous concept topic would be a discussion of why Europeans rarely order lattes in the afternoon or why an Americano is called an Americano.