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.