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


Including equations in DITA content

By Jakobswiki (Own work) [CC BY 3.0 (http://creativecommons.org/licenses/by/3.0)], via Wikimedia Commons

Sample Butler volmer equation. What DITA elements would you use to display this equation?

There are three possible containers for equations in the equation domain: equation-inline, equation-block, and equation-figure. Choose the DITA elements that makes the most sense for your equations: inline, in a separate block, and/or an equation or series of equation with a caption. Read more

Should you use tables in DITA?

By Byzantinischer Maler um 1020 [Public domain], via Wikimedia Commons

This table is from the year 1020. It’s time to consider smarter ways of building and maintaining tables.

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 comfortable using tables. And you 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. Read more

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. Read more

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

How to organize a bookmap: nesting under the element

How you organize a bookmap will affect how easy or difficult it will be for you to maintain and update your content. Should you nest a DITA map under the <chapter> element in a bookmap, or should you nest topics directly under the <chapter> element? 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

DITA Bookmaps or regular DITA maps?

Bookmaps enable users to organize their DITA information into front matter, parts, chapters, and back matter. Typically, publications are created from a bookmap while DITA maps are used for Read more

Predicting costs and benefits from implementing a DITA solution

This is a break from our posts about markup, but if you’re going to do DITA, you should also be able to figure out what it’s costing your company.

Reuse in DITA: reusing topics

DITA enables reuse on many levels. This post discusses some tactics for reusing topics. Read more