Task Topic

1.

Task Topic: a Brief Introduction

2.

What is a topic?
In the context of technical writing, a topic is an article discussing
one particular self-contained subject. Typically, topics are linked
with each other, making up a web of information.
What are the general types of topics?
Task topic—describes how to accomplish a specific goal by
completing a procedure.
Concept topic—describes an idea or provides some general
background of the subject.
Reference topic—provides quick access to fact-based information.

3.

QUIZ
What topic title looks better:
A. How to add employees to the Rating page
B. How to add, look up, and delete employees on the Rating page
What topic title looks better:
A. Sending DICOM images to reading doctors
B. Using the built-in SFTP connection to exchange DICOM files
What’s the recommended maximum number of steps per topic in a user guide?
A. 3
B. 10
C. 15
D. 30

4.

Create one topic for one task (procedure).
Example:
✔ How to add employees to the Rating page
✘How to add, look up, and delete employees on the Rating page
Separate task information from conceptual or reference information
Brief conceptual explanations or references are OK, especially if they work in the
topic. The main idea is not to overload the topic with non-procedural information.
The user comes for how-to-do guides, so give them what they come for.
Focus on user goals, not product features
When naming your topic, specify the goal the user want to achieve instead of the
product features.
Example:
✔Sending DICOM images to reading doctors
✘Using the built-in SFTP connection to exchange DICOM files
Keep it brief
If you feel that your topic is too long or too hard to embrace, break it into smaller topics or
subtopics. Don’t create tasks with too many steps. It’s recommended that your topic
shouldn’t exceed 10 steps.

5.

QUIZ
What’s the best title for a task topic
A. PACS bridge
B. PACS bridge installation
C. Install the PACS bridge
D. PACS bridge: 4 installation steps
What is the best step description?
A. Pour the water into the water tank.
B. It is essential that the water tank has some water inside.

6.

Task topic elements
1. Title: specifies the task
2. Short description: introduces the task
3. Context information: gives the task background, describes the benefits of the task
4. Prerequisites: tells you what should happen or what you need to do before you begin
the task
5. Procedure step: a significant action (sometimes a sequence of actions)
6. Additional information for a step/task: notes, warnings, etc.
7. Step result: what happens when you complete the task
8. Example: a practice case, a piece of code, etc.
9. Task result: what happens when the task is completed
10. Postrequisites: what you need to do after the task is completed

7.

Task topic elements
Topic title
The title names the task you want to perform. It should help the user understand
what they want to do: send an email, add a person to the contact list, etc. A task
topic title should help the user distinguish it from other topics (concept,
reference).
The best practice is to use verbal forms (including gerund) or “how-to”
constructions:
✔ Gerund: Configuring the database
✔ Imperative construction: Configure the database
✔ How-to construction: How to configure the database
The titles should be consistent (only gerunds, or only “how-tos”).
It’s not recommended to use nouns:
✘Database configuration
✘Database

8.

Task topic elements
Short description
Short description introduces the task in a short, concise manner. Normally, it shouldn’t
exceed 50 words and include lists. Sometimes, descriptions are applied to separate steps
of a task.
Best practice: Don’t use imperative sentences so that the users understand it’s not a
procedure step. Don’t use lists or tables. It should be a short piece of text.
Examples: As an assessor, you can rate your teammates using a 5-point numerical rating
scale.
Context information
Context provides task background in addition to the short description. It says where and
when to perform the task or describes the benefits of the procedure.
Example: Report templates can be helpful when you read many similar studies within one
diagnostic facility.
Prerequisites
Prerequisites say what the users need to know and/or what conditions need to be met
before they start the task. Unlike context, prerequisites contain a call to action.
Best practice: use imperative constructions.
Example: Make sure your diagnostic equipment is properly connected to the computer.

9.

Task topic elements
Procedure step
A procedure step is a significant action to be taken to complete the task.
Best practices
Use not more than 10 steps per topic (instead, you can split your topics somehow).
Use imperative sentences so that the users understand they need to do something.
✔Pour the water into the water tank.
✘It is essential that the water tank has some water inside.
Write one step per significant action. Short steps can be combined. Just keep it brief and
logical.
Example: Combine “4. Click OK” and “5. Click Save” into one step: “4. Click OK and click
Save.”
Know your audience and their background. If your target audience consists of Project
Managers and system administrators, you probably don’t want to explain them how to use
a drop-down menu.

10.

Task topic elements
Types of procedure steps
Mandatory (Regular). A step required to complete the task. Without this step,
the task cannot be completed. Typically, it’s an imperative sentence (or several
sentences).
Example: Tap on the “Send” icon to send the message.
Conditional step. Required only if some condition is true.
The best practice is to use the “if” construction.
Example: If the signal source is “Antenna,” switch to the HDMI-1 source.
Optional step: Doesn’t need to be taken to complete the task.
The best practice is to specify that it is optional so that the users know it can be
skipped.
Example:
Optional: To receive email notifications, select Email Notifications.

11.

Task topic elements
Procedure steps presentation
Procedure steps should be created as a numbered list. Mind the text and image alignment.
Steps in one-step procedures are recommended to mark with bullets (Microsoft).

12.

Task topic elements
Substeps
It is recommended to use not more than 1 level of substeps not to confuse the readers.
Mind the text and image alignment.

13.

Task topic elements
Concluding the task
Where applicable, use the following elements to conclude the task topic:
An example:
For example, to set February 3, 2022, enter 2022-03-20T00:00:00.
Postrequisites:
Example: Once you set your equipment to sleeping mode, turn keep the power on.
Results:
Example: Once the user is removed from your contact list, you will see a toast message:
Data has been successfully updated.

14.

Task topic elements
Concluding the task
Where applicable, use the following elements to conclude the task topic:
An example:
For example, to set February 3, 2022, enter 2022-03-20T00:00:00.
Postrequisites:
Example: Once you set your equipment to sleeping mode, turn keep the power on.
Results:
Example: Once the user is removed from your contact list, you will see a toast message:
Data has been successfully updated.

15.

References
1.
2.
3.
4.
5.
Bellamy, L. (2011) DITA Best Practices: A Roadmap for Writing, Editing, and
Architecting in DITA. Indianapolis, Indiana: IBM Press
Writing Task Topics: EdX StyleGuide
Veeam Technical Writing Style Guide
Microsoft Corporation (2012) Microsoft Manual of Style Fourth Edition.
Redmond, Washington: Microsoft Press
OASIS Standard, Darwin Information Typing Architecture (DITA) Version