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

The DITA Code Review (Content Audit) – put your content on track to success

A DITA Code Review is a collaborative process, building skills and keeping your DITA implementation on track towards semantic markup. Make DITA content auditing part of your team culture.

Review of your DITA content for semantically correct markup is referred to as a DITA code review or a DITA content audit.

What happens in a DITA content audit (DITA code review)?

The auditor(s) review DITA source files and check tagging in the content. The editors/writers whose content is reviewed get practical, hands-on feedback towards implementing DITA best practices.

Who does a DITA content audit?

Any member of the team who is versed and conditioned in semantic markup can lead a DITA code review. Ideally, the review auditor(s) will be or will include at least one person from outside the team who can:

  • Benchmark against DITA best practices
  • Compare to other teams in the organization (creating healthy competition between teams)

Why review your DITA markup

DITA has lots of promise. Semantically correct DITA markup is the key to successfully realizing that promise.

Semantic DITA markup can enable:

  • filtering content by detailed conditions,
  • displaying expandable/collapse content,
  • applying automation to display, and
  • enabling rapid identification of issues that need to be checked or modified when your product updates
  • … and much more, such as intelligent tools that link error messages or support requests to content require semantic tagging to work.

For example, a call to help that references a specific task or error can automatically map to the appropriate content – if the content has meaningful semantic markup.

Does your DITA separate content from formatting? If not, the presentation is likely to be inconsistent, problematic across emerging platforms, difficult to maintain over time, and time-consuming and costly across localization combinations (for different languages and markets).

When should you do a DITA code review/content audit?

DITA code reviews should start early in your DITA implementation. Content auditing helps your team make the shift from tagging for formatting to tagging for semantic meaning. Shifting to semantic markup is not easy, and the content review helps keep your team on track to successful DITA implementation.

The earlier in the process that you start content audits, the earlier writers and editors can recover from problematic tagging and acquire healthy semantic tagging habits. The earlier this happens, the smaller the scope of problematic DITA content created.

Over time your content will tend to regress. New writers come on board. Experienced writers tend to slip back into old habits. Content needs to be added in a rush and semantic markup tends to suffer. Implementing a regular cycle of code reviews helps you keep your content effective and agile. While the frequency of code review will drop over time, content auditing should become a regular part of your team culture.

Every DITA implementation needs a DITA code review. (Read Is Markup Mentoring for Me?)

Use tools whenever possible to turbo-charge your content review

Consider usage of the <b> element in DITA. Bold has no semantic meaning. Getting users to not use <b>, and use a semantically meaningful tag for the content (such as <uicontrol>), is part of the DITA mandate.

You can use the CSS to focus writers and reviewers on use of problematic markup. For example, you can display content marked with <b> on a bright red background.

Consider use of search scripts to identify “known issues” (such as overuse of conditions).

The content audit should be a resource for writers – not an Orwellian experience

Writers and editors don’t want to feel that their professional autonomy and competence is under attack. The writers do want to feel supported in a challenging environment. Part of the goal of the content audit is to provide support, in the form of positive, focused, and practical feedback that writers and editors can implement immediately.

Sample scenario for a content audit

  1. The auditor(s) and the editor/writer select a representative set of 10 topics. (Include task content as much as possible in the set.)
  2. The auditor(s) spend 15-30 minutes per topic and provide feedback on the topics.
  3. The auditor(s) meet with the writers and editors to review the feedback. Editors and writers have an opportunity to explain their approach – and get supportive feedback towards semantic markup.
  4. Writers and editors then have a chance to work on 5-10 additional topics and present the topics to the auditor(s) for review. The auditors will provide positive feedback where semantic markup has been implemented and will point out where improvements should be made.
  5. This step can be repeated for an additional round as needed.
What happens when source content is bloated? DITA, minimalism, and agile development.
DITA, minimalism, and agile content

Helping Writers Succeed with Great DITA, Minimalism, and Agile Content

Too often, when we work on a DITA implementation we spend a lot of time on the bells and whistles of our CMS or the DITA-OT publishing scripts. But, often the content is bloated, uses unsemantic markup, is riddled with duplication, and suffers from condition overload. Read more

How to add a DITA specialization to oXygen Editor or oXygen Author

Congratulations. You just got your brand new DITA specialization. And, you want to use it.  Follow these instructions to successfully integrate your DITA Specialization to oXygen Editor or oXygen Author.

These instructions apply when the DITA specialization is available as a DITA Open Toolkit plugin. Read more

Including equations in DITA content

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?

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?

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