Concept, task, reference: three types of technical documentation
One of the most important aspects of technical writing is effective organization, which not only improves your content’s quality and ease of use, but makes it easier to revise and reuse. One common method for organizing content is DITA (Darwin Information Typing Architecture): a modular approach to creating content that emphasizes topic-based writing.
In topic-based writing, content is split into a number of topics that deal with individual subjects. In this article, we’ll focus on DITA’s information typing framework, which involves sorting topics into one of three categories: concept, task, or reference.
- A concept topic gives an overall explanation of a subject.
- A task topic gives instructions for completing a task.
- A reference topic gives specific facts.
DITA requires you to identify what kind of information you’re presenting to the reader and organize it into separate topics. Most technical documentation uses all three types of topics.
The way you use information typing varies depending on the documentation’s length. Longer documents will usually have multiple topics of each information type, and they may be organized differently than shorter documents, which could have only one or two topics in each information type.
For example, let’s say you’re writing a guide to using a library’s 3D printer. You might use the three information types in the following way for long and short documents:
| Information type | Quick start guide (short document) | User guide (long document) |
| Concept |
|
|
| Reference |
|
|
| Task |
|
|
Organizing these topics by type helps the reader use your content more efficiently. Ideally, each topic has its own heading within the document.
Writing concept, reference, and task topics
When writing topics, use different formatting and structuring for different topic types. This will make your content easier to read and understand.
Writing topic titles
Use parallel topic titles for different information types, like in the table below:
| Concept | Reference | Task | |
| Begin with | Noun or noun phrase | Noun | Gerund |
| Example | “3D printer services at the library” | “Costs for 3D printing” | “Using a 3D printer” |
Structuring topics
For concept topics, use full sentences and paragraphs. Since you’re providing an overview or explanation, writing short paragraphs is usually a good way to engage the reader.
For task topics, use ordered lists. Each step usually describes one action, and the steps are presented in the order that the reader will perform them.
For reference topics, use tables and/or lists. Use tables to display product specifications for multiple products and/or scenarios, and lists to define terminology or identify required supplies.
Ordering topics
Organizing your content consistently will help the reader predict where they can find the information they need, even if they read the content out of order.
When structuring a document, use a concept topic as an introduction – it explains why the document exists, who it’s for, and what a reader can expect to find in the related task and reference topics. Depending on the subject, the next section may be a task or reference topic.
Consider the topic’s subject, in addition to its information type, when organizing topics. For longer documents, grouping topics by subject, and then organizing within those subjects by concept-task-reference or another order is usually the best method.
Final thoughts
The DITA framework helps you create better technical content. From the writer’s perspective, DITA helps create content that is easy to repurpose and reorganize, which saves time and improves consistency. From the reader’s perspective, the content is easy to navigate, which makes it easy to use. Using DITA will help you create higher-quality technical content in less time.