Separating our original topics into DITA is not always easy.
We find that we have a mixture of DITA topic types within our original topics.
We pull out the information from the original topic and place into the
appropriate DITA topic types. It’s not always easy to know what information
goes where. We’ve defined the DITA topic types to focus our writing.
- Do they need to understand something? It’s a concept.
- Do they need to do something? It’s a task.
- Do they need to know the details about a field? It’s a
reference.
DITA is another way of writing the inverted triangle.
Concepts are at the top, giving the high level ideas. Tasks are in the middle,
providing the step-by-step instructions for users unfamiliar with the actions.
References are at the bottom, showing the details of what a user needs to input
in the fields on the screen.
Concepts
In our manuals, concepts are the overviews. They explain the
theory about why a user has to the tasks. Concept answers the following at a
high level: Who does it? Why do they do it? When do they do it? Where are they
in the application when they do it (the general area)? What are the general
tasks they do?
Tasks
Tasks answers the following so they can do the task: When do
they do it? Where specifically are they in the application when they do it
(what page are they on)? How do they do it (what steps do they follow)?
References
References house all those pesky details for the fields.
What limitations are on the fields? What are the details they need to know to
do the steps? Are there any special scenarios where you should not do
something, even if you can?
Another benefit of the separation of topics is based on the
experience of users with the application.
New users need all three types of topics to understand how
to work effectively in the application. They need to know the concepts behind
how the application helps them work. They need to know how to work in the
application, and they need to know the details of what to put in the fields.
Experienced users know the concepts. They need the support
of steps in the tasks to make sure they do them correctly, and they need to
know the details of what to put in the fields.
An expert user knows the concepts and how to do the tasks.
They only need the support of the field details and limitations.
In training our writers to categorize the information in
these ways, they are able to place the information into the appropriate topic
types. There is some overlap between concepts and tasks, and tasks and
reference. The key is on the level of detail in each topic type.
