14 Jul Topic-based Authoring
Concept, Task or Reference!
- Punit Shrivastava
Technical Documentation is about conceptualizing the content rather than just developing the content. It follows specific guidelines to conceptualize the thought process required to create a document. While all the technical writers author a document to follow the common goal of helping the customers in the best possible way, the varying technical terms used in documentation guidelines may confuse some and might not be always recommended to use.
The correct placement of content helps users understand the flow of documents and improves readability. With evolution, research and customer feedback, the presentation of unstructured content has been replaced with a thoughtful process of topic-based writing consisting of Concept, Task, and Reference, which in today’s technical writing space is one of the popular approaches to achieve the goal of documentation impact and customer satisfaction on the overall product.
While some Technical Publications / Documentation teams follow this approach only as a guiding process, others prefer to bind it under the strict rules of DITA using XML with the help of supporting technical documentation tools. A tool like MadCap Flare allows one to follow only the process, while some tools like Oxygen XML editor make it mandatory to follow the rule book.
As every approach has its own set of logic, let us skip the argument about which approach to follow. In this article, let me make an effort to help you understand the basics of Concept, Task and Reference with some examples.
Origin of Terms
Concept, Task and Reference as specific terms owe its origin to the continuous research and evolution in the field of technical documentation. The theory of Information Mapping brought such terms to the fore. Rober E Horn categorized content into six types of information: Procedure, Process, Principles, Concept, Structure and Fact.
Under DITA’s emphasis on topic-based content, the categories were reduced primarily to Concept, Task and Reference. The other two identified categories are Glossary and Troubleshooting.
Definitions and Usage
While explanations may vary when you dig in deep, let us understand the basic differentiation among the three.
- A Concept topic provides answers to every important WHAT related to the subject.
- A Task topic helps to find answers about every HOW to related to the subject of the topic.
- A Reference topic helps to find answers about WHICH additional information the users need to know about the subject.
After completing the first two key steps of documentation – Product Understanding and User Persona; the WHAT, HOW, WHICH questions help you decide the type of topics to create!
Concept and Reference topics contain descriptive elements of the content while a Task topic contains procedures to help users perform a small or major action. All the three follow standard defined rules that you need to apply while creating topics. For example, Concept needs a short and long description- text or visual, paragraphs or tables. Task needs less description and more procedures, divided into optimized steps.
The content flow in a topic is defined by which type you selected. In Task, you can focus primarily on writing simple and direct steps instead of paragraphs. The lines are written with focus on an interactive tone as if you are talking to the user directly.
The reference topics generally include content such as concept of a subject, syntax of commands, tables, instructions for subject that may not be required by all users.
Popular Structure of the three topic types
Summary
Topic Type
Main Purpose
Answers
Common Format
Concept
Explain ideas
What / Why
Paragraphs, explanations
Task
Perform actions
How
Numbered steps
Reference
Provide facts
Which details
Tables, syntax, specifications
Details
Topic Type
What to expect
Writing Style
Concept
- WHAT something is
- WHY it matters.
- Includes background knowledge, definitions, and understanding.
- Descriptive
- Informative
- Paragraph-based
- Answers:
- What is it?
- Why is it used?
Task
- HOW to
- perform an action or
- complete a procedure.
- Primary: action-oriented and step-focused.
- Direct
- Instructional
- User-action focused
- Answers:
- How do I do this?
Reference
Factual or lookup information users may need during tasks. It focuses on WHICH details users need to know.
- Concise
- Structured
- Easy to scan
- Answers:
- Which information do I need?
Typical Structure
Concept Topic
Task Topic
Reference Topic
1. Heading: Noun or concept-based term
(Example: <Name> or Overview or Introduction)
2. Brief overview of the concept
(Provide context and purpose)
3. Key Features or Components
(Use bullets or subsections)
4. Benefits / Use Cases
(Why users need it)
5. Additional Explanation
(Diagrams, visuals, examples, notes)
6. Related Links
(Link to tasks or references)
1. Heading: Action-oriented term
(Example: Adding <Name> or Configure <term>)
2. Short description
(State the goal of the task)
3. Prerequisites
(Requirements before starting. For example, permissions, setup, tools, login access)
4. Procedure / Steps
(Numbered instructions. One action per step)
5. Substeps (Optional)
(Additional details under a step)
6. Expected Result
(What happens after completion)
7. Post-Requisites / Next Steps
(Related tasks)
1. Heading: Fact-based terms
(Example: API Error Codes)
2. Short Description
(Explain what information is available)
3. Reference Content
(Tables, Syntax, Parameters, Commands, Specifications, Field descriptions)
4. Examples
(Sample values or outputs)
5. Notes / Restrictions
(Limitations or warnings)
6. Related Information
(Links to concepts or tasks)
Before writing a topic, spending some time to assess the purpose of the topic and how it benefits the reader, could help you decide which one to create: Concept, Task or Reference. Mapping a combination of all such topics related to a specific purpose helps you achieve the final goal of creating a guide.
Keeping in mind the ultimate goal of customer satisfaction, you can take a call on whether to follow these with the defined rules of DITA or customize the defined process.
About the Author
Punit Shrivastava is involved in mentoring and helping the Technical Writing community. He prefers sharing knowledge and learning with the focus on having a skilled community. He has 20+ years of experience in the field of writing that spreads across writing for English daily, The Asian Age, and 17+ experience in technical documentation for multiple software companies.
Sorry, the comment form is closed at this time.