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”|