What’s new, cool, useful and powerful in DITA. Learn DITA best practices.

Should you use tables in DITA?

Writers are conditioned to using tables. We are creatures of habit, and using tables in DITA seems to come naturally if you are used to writing in Word or FrameMaker.

Bottom line: When you need to present information that will be table-like when read, your default preference should be for definition lists.

We know that you are used to using tables. And love merging cells and doing all the cool stuff that oXygen Author and XMetaL Author can help you do with DITA tables. Get past it. Consider using definition lists wherever possible.

What’s wrong with tables in DITA?

Telling a technical writer to try and avoid tables is a bit like telling Genghis Khan to avoid conquering. It’s just what we do. This is true — but we want to get past it. Using tables in DITA is sometimes necessary, but often we can get ahead by avoiding use of tables.

Tables invite endless tampering with settings for column width. In most cases, get over it and get past it. Go for <dl>, definition lists.

The key point here is “most cases”. Most, but not all. If it’s absolutely critical that you display content (such as images and descriptive text side-by-side), and you don’t want to configure <dl> so that <dt> and <dd> display side-by-side in general, or if you absolutely must have a large number of columns, or if you need to merge cells. then go for tables.

Your next steps

Click here to learn more about <dl> in DITA. Reach out to Method M for help with all of your DITA needs.

A definition list sample — an alternative to tables in DITA

A sample definition list with a heading:

  <dthd>Image File View Selection</dthd>
  <ddhd>Resulting Information</ddhd>
  <dt>File Type</dt>
  <dd>Image's file extension</dd>
  <dt>Image Class</dt>
  <dd>Image is raster, vector, metafile or 3D</dd>
  <dt>Number of pages</dt>
  <dd>Number of pages in the image</dd>
  <dd>Names of the fonts contained within a vector image</dd>

How to describe choices in a DITA task topic?

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 if we 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.

Polygamous or Monogamous DITA Topics?

DITA topics should focus on one idea

Keep your DITA topics focused. One topic. One idea.

Embedding multiple topics inside one topic file (polygamous topics) is not good practice. We call these topics, “polygamous topics”. If, in real life, polygamy tends to be a really bad idea, the same is true for DITA topics.

The golden rule for DITA topics is Read more

Nest DITA topics under a topic or under a topichead?

nesting DITA maps and DITA topics

For the red-footed booby (Sula sula) nesting comes naturally. For DITA projects, nesting topics and maps requires some forethought and planning

When you have a collection of DITA topics to nest, or individual DITA topics to next, you have a lot of choices. Often, too many choices. In a ditamap, you can nest DITA topics under a topic, <topichead> or <topicgroup>. In a bookmap, you can nest DITA topics or a ditamap under the <part> or <chapter> element. Read more

Group topics in DITA maps

Referring to DITA maps from a bookmap or from another DITA map provides a great way for grouping topics. You can refer to the DITA map in the bookmap, or in a parent ditamap, whenever you want to include the collection of topics in the bookmap.

Tip: Read more