Concept, Task, Reference:
A practical guide to choosing the right topic type
Real World DITA Conference
September 2009
Larry Kunz
[email protected] www.sdiglobalsolutions.com
Outline
The Topic Types
Best Practices
Naming Your DITA Files
Resources
The Topic Types
Task
Concept
Reference
Generic (no particular context)
Glossentry (special type)
The Topic Types
Why not just use generic topics?
Clearer focus
Specialized elements
Better cross-references
Task
From the DITA 1.1 Language specification:
Task topics answer "How do I?" questions, and have a
well-defined structure that describes how to
complete a procedure to accomplish a specific goal.
Use the task topic to describe the steps of a
particular task, or to provide an overview of a higher-
level task.
Task topics answer questions like :
How do I do this?
What do I need before I start?
What will happen when I finish?
(continued)
Task
Task topics should contain:
Steps to complete a specific operation
Replace the printer cartridge
Set up the database
Complete the application form
Prerequisites
Brief explanation of the context in which the steps
are performed
Examples (optional)
Results (optional)
Next steps (optional)
Task topics should not contain more than a small
amount of conceptual or reference information
(more on that later)
Concept
From the DITA 1.1 Language specification:
DITA concept topics answer "What is..."
questions. Use the concept topic to introduce
the background or overview information for
tasks or reference topics.
Concept topics answer questions like :
Why am I doing this?
What principles do I need to keep in mind?
Whats the big picture?
What other things might be affected by the
choices I make?
(continued)
Concept
Concept topics:
Set the context for a task or tasks
Less than 1 or 2 paragraphs can go into the
task topic using a <context> element
Develop knowledge that the user needs
to perform the tasks
Example: What is storage management?
Detail-oriented knowledge goes into
reference topics
Describe how tasks fit together
Reference
From the DITA 1.1 Language specification:
Use the reference elements to describe regular
features of sets of things, most commonly the
commands in a programming language. However,
this format is also suitable for recipes,
bibliographies, catalogues, and similar collections
of structured descriptive prose.
Reference topics answer questions like:
Which option do I want?
What does this mean?
(continued)
Reference
Reference topics should not contain:
Steps from a task
Contextual, background, or overview
information
Examples of what they should contain:
Lists of options, parameters, etc.
Extended examples
Troubleshooting tips
(symptom/cause/fix)
Best Practices: Shrinking the Gray Area
Best Practices: Shrinking the Gray Area
Concept or Reference?
1. The simple rule of thumb: Is it mostly prose,
or mostly tables and lists?
In many cases this is enough to decide
Tables and lists almost never go into a concept
topic
2. If prose, what does it say?
3. How often will a reader need to use it?
Once, to gain understanding (concept)
Often, to look up details (reference)
Best Practices
Concept or Reference?
Example 1
Summary of medical requirements for
traveling outside the U.S.
Best Practices
Concept or Reference?
Example 1
Best Practices
Concept or Reference?
Example 2
How it works descriptions for minor
(or optional) product components
Best Practices
Concept or Reference?
Example 3
High-level summary of a process that
contains several different tasks,
perhaps in different sequences
Best Practices
Reference info in task topics
Some reference info in a step is OK
But move it to a separate reference
topic when:
It interrupts the task flow
(this is subjective)
The reference info can support
several different tasks
Best Practices
Too much for a task topic? (Before)
Best Practices
Too much for a task topic? (After)
Best Practices
Avoid in-line cross references
Easier to avoid stale links
Easier to keep track of all the links;
they live in a central place
Inline links tempt users to click them
Use reltables instead
Best Practices
Organizing the topics
What information model(s) is/are you using?
Book: Imagine the material being read
front-to-back
Context-sensitive help: Group C,T, and R
topics with one another
YMMV
Note: This might help you decide whether a
specific topic should be a C or an R
Best Practices: Summary
Overriding considerations:
What do the tasks look like from your
users point of view?
Where is the information being reused?
What information model(s) is/are you
using?
Naming Your DITA Files
Your goals:
Easily view and manipulate file
names, for example in the CMS list
Easy for others (new team members,
or people who reuse your files) to
understand what the topics contain
Distinguish C,T,R topics
Easier to build a reltable
Easier to identify where topics should go
when building a new map
Naming Your DITA Files
Make names meaningful, not cryptic
Instead of: dc_c
Try: database_connections_c
Dont just parrot topic titles
Instead of: settinguptheprimaryserver_t
Try: setup_primary_server_t
Instead of: parametersthataffectsystemperformance_r
Try: perf_parms_r or performance_r
Keep names distinct from each other
Instead of: db_setup_t and db_setup_r
Try: db_setup_t and db_setup_parms_r
Naming Your DITA Files
Avoid using code names for products that
are still in development
Instead of: mothra_installation_t
Try: ip_gateway_installation_t
Use names that reflect topic contents, not
metadata
Instead of: department_installing_t or writername_installing_t
Try: productname_installing_t
Try to have a consistent approach
Instead of: server_migration_c and migrating_databases_c
Try: server_migration_c and database_migration_c
or migrating_servers_c and migrating_databases_c
Naming Your DITA Files
Summary of recommendations:
Put yourself in the writers shoes
The underscore character is your friend
Be descriptive without being verbose
Use suffixes: _c, _t, or _r
Consistency is a virtue
Promulgate file naming conventions as
part of your style guide
Resources
DITA 1.1 overview
http://docs.oasis-
open.org/dita/v1.1/overview/overview.html
DITA 1.1 architectural specification
http://docs.oasis-
open.org/dita/v1.1/CS01/archspec/archspec.html
DITA 1.2 implementation status (list of new features)
http://wiki.oasis-open.org/dita/ImplementationStatus1.2
dita-users Yahoo group
(great resource for getting your questions answered)
http://tech.groups.yahoo.com/group/dita-users/
Your turn
Q & A
