Adopting DITA means you need to make a switch from document or chapter-based writing to topic-based writing. For writers being exposed to DITA for the first time, this shift in thinking and writing tends to be the hardest part of the transition.

At the core of topic-based writing is the DITA task. Master the task and you start mastering DITA content (or any topic-based content). Concepts and references are important too, but once you have mastered the task, everything else just falls into line.

Your DITA task will be the core of your content. The task topic is your primary way of instructing your users and guiding them through their relationship with the product—from setup to advanced configurations, tasks are going to be the most frequently read topics. If you identify the right tasks to document and document those tasks in a usable way, your documentation will be valuable and usable and your user will be happy with their product. Happy users are always good for business.

If you are working with legacy content, knowing the model and purpose of the DITA task will help you during your conversion. If you have content that doesn’t map one-to-one with the elements of a DITA task, then you’ll know that you have some pre-conversion work to do.

Purpose of a Task

The purpose of a task is to tell a user how to do something. From logging in for the first time to configuring an advanced combination of features, the task walks the user through the steps and provides important contextual information as well.

The task is intended to be streamlined, easy to read, and easy to follow. To get your task down to this minimal, usable core of material, you need to provide just the information that the user needs to complete the task and nothing more.

A well-orchestrated task has the right information in the right location—and nothing extra.

Focus

How long should a task be? It needs to be long enough to stand on its own but short enough that the user won’t give up partway through. Ideally, to be the most useful, a task should be no more than ¾ of a “page” in length (note that page lengths differ—a page is considerably shorter for mobile outputs, for example). However, there are valid use cases for both a one-step task and a 15-step task, so task length really depends on the content.

I think the better question here is not about length, but about focus: What should the focus of my task be? If I’m writing about logging in to the system, do I include every way to log in and as every type of user?

The answer is usually no. The more focussed your task is, the more usable it is. Place yourself in the users’ shoes and ask yourself what they need to know. Logging in to the system becomes a whole set of tasks (from which you can re-use steps extensively through the conref mechanism and/or use conditional metadata to make writing and updating faster and easier):

  • Log in for the first time (for admin)
  • Log in for the first time (for user)
  • Log in from a mobile device (if different)
  • Reset your lost password (for admin)
  • Reset your lost password (for user)
  • Log in as a special user
  • Etc.

This type of focus is invaluable to your end users. However, it’s the type of focus that is difficult to correctly identify without doing user testing and getting ongoing user feedback. If your company doesn’t provide an opportunity to get direct feedback from your users, you are relegated to either guessing how users will use the product or writing feature-based content; neither is a recommended way to write.

If you find yourself documenting a task based on a GUI feature, mechanism, then you may be missing the focus that your users need. Make sure you’re identifying and writing for the business goal rather than the product functionality. A correctly focussed task often strings together many pieces of product functionality.

Instead of…
 Focus the task(s) on…
Using the print feature
  • Exporting to Excel
  • Sending a PDF for review
  • Publishing for mobile devices
  • Printing a hard copy
  • Managing your printer options
  • etc.
Configuring the x threshold
  • Maximizing efficiency in a large deployment (will include configuring x threshold as well as other widgets/settings)
  • Maximizing efficiency in a medium deployment
Using the MyTube Aggregator feature
  • Creating a channel of your favourite videos
  • Growing your reputation/community
    following

Once your task is properly focussed, the question of length usually answers itself. Always keep in mind that users don’t like to read documentation, so make every task as succinct as you can.

Core Elements of a Task

Use the core elements of a task as your tools for writing a clear, clean, streamlined task that is usable and functional.

Element  Description Example
Title
  • Clearly written description of user goal for the task
 Create Daily Reports
Short 
  • Complements the title
  • Used in navigation and search results
  • When combined with the title, helps users decide whether to navigate to a specific topic
  • Uses words that bridges the gap between product terminology and user terminology
 Daily reports summarize the system performance in graphical format over the last 24-hours
Pre-requisites
  • What the user must complete or have at hand before starting this task
  • The line sometimes blurs between the first step and a pre-requisite; use common sense
 You must have administrative rights
or
You must have configured your server for access through the cloud
Context
  • Explains why the user would perform this task, what their goals are, and places the task in a larger context
 Use and customize daily reports to get a snapshot of the system’s health and identify any trending issues or problems before they become critical
Step Command
  • Tells the user what to do for each step succinctly and with no extra words
  • Covers the action they must take and no more
 Log in to the command console

Step Info

(Optional)
  • Additional information about the step command that is essential for the user to know about that step, but is nonetheless not part of the action they must take
  • Can often include tips (which should be in a note element inside the info element) or special circumstances that need to be noted
  • Is a troubleshooting element for the user—if they cannot perform this step (e.g. forgot password), give them enough information here so they can move forward
  • With the next two elements, often the content that gets automatically stripped out when publishing for mobile devices
 Your password was created as part of the installation process
Step Result (Optional)
  • Tied to particular step, this is the result of the user taking the step
  • Can be omitted when the result is obvious
 Your daily metrics display
Step Example (Optional)
  • Tied to a particular step, this is an example of what they see or input
  • Can be omitted when it doesn’t apply
 A list of metrics, areas, or a screenshot
Sub steps (Optional)
  • Set of sub-steps that walk the user through the details of a complex step
  • Can often be used when a command becomes too long (you are trying to put too much information into one step)

1.  Restart the agent

a. From Task Manager, locate and select the agent

b. Click Stop

c. Wait 30 seconds

d. Click Start
Step Choices
  • Can be used if the step can be done in different ways for different purposes
 If you prefer nightly reports, enter 6:00 a.m.
Task Result (Optional)
  • The result of the user finishing the task correctly
  • Should tie back in with the short description and context
  • Can be omitted if the task result is obvious or doesn’t apply
 Customized daily reports that help you identify trends and summarize progress are now available on your Central Admin interface and are available from a drop-down list for all other administrators
Task Example (Optional)
  • An example of what a correctly performed task looks like
  • A way to provide specific details without being specific in the steps
 A screenshot or code example
Post-requisites
  • What the user must do after they have completed this task

 

 Re-generate all reports to include your new reports in the next bulk export

Note: There is another task available called a “Machinery Task” that has more elements and more ways to organize those elements. It is appropriate for content that covers assembling and maintaining machinery. Check the DITA 1.2 (or the latest) specification for details.

What is not included in a DITA task is a place to add detailed reference material, rationalization for performing a particular step, or complex or bifurcating task steps that cover multiple scenarios (Linux and Windows, for example).

  • Detailed reference material would be written and chunked separately in its own reference topic and either placed adjacent to this task or linked to via the relationship table in the ditamap.
  • Rationalization for each step (why you perform each step) is not needed. It clutters up the step with information that is not essential. Leave it out or add an overall explanation into a concept topic instead.
  • Bifurcating tasks (usually written in long tables in legacy materials where the user is supposed to skip down to the rows that apply to them) are no longer needed in DITA. Make each scenario its own task or use conditional metadata, and/or define your re-use strategy instead.
Fig: Example of the common elements used in a task (in an XML editor with inline elements showing)

Tasks are really the core of great, usable content. The more focussed and streamlined your tasks are, the more valuable your users will find them. It’s important that you use the correct task elements for the correct type of content. Use the elements as your guide to mastering the task. If you’re working on legacy content, then use styles or formats that map to these elements to ensure your conversion to DITA is nice and easy.