How to describe choices in a DITA task topic?

Duncan Lilly [CC BY-SA 2.0 (http://creativecommons.org/licenses/by-sa/2.0)], via Wikimedia Commons

When the reader needs to make a decision, use the correct DITA element.

Why use <choices> or <choicetables> instead of <ol> or <ul> in a task topic when you need to choose what to do next? DITA markup offers different options for describing choices in a DITA task topic.

The benefit of <choices> or <choicetables> is that the markup is semantic! When you use <choices> or <choicetables>, the machine (and the writer!) understands explicitly what you are talking about.

Decision rule – <choices> or <choicetables> for choices in a DITA task topic

Use <choices> where the customer has reached a decision point and must choose one of the options.

  • Example: take Route 66 to Boston or Route 81 to Ithaca.

Use <choicetable> where the customer has different options to get to the same result.

  • Example: to save, click CTRL+S or choose File > Save).

What’s wrong with using ordered or unordered lists to indicate choices in a DITA task topic>

Using <ol> or <ul> eliminates semantic markup! Using <choices> or <choicetables> explicitly indicates the kind of juncture the reader has reached — and forces the writer to state if no matter what the choice, the end result will be the same (<choicetable>), or if the choice selected will lead to a different outcome (<choices>).

Ultimately, the reader will have a clearer idea of his or her options when you pick the correct, semantic markup for choices in a DITA task topic.

Your next steps

Click here to learn more about the <choices> or <choicetables> elements in DITA. Reach out to Method M for help with all of your DITA needs.