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.

DITA Code Review Tip: use CSS to highlight problem areas

Use tools whenever possible to turbo-charge your content audit/DITA code review.

Consider usage of the <b> element in DITA. Bold has no semantic meaning.

Getting users to stop using <b> and use a semantically meaningful tag instead for 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> as purple text on a bright yellow background.

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

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

Information Architecture

information architecture

Use our DITA information architects to help you succeed.

Here are just a few of the issues that our expert information architects will help you work through:

    • How will your DITA implementation affect your ability to publish translations quickly and inexpensively?
    • What choices can you make for content reuse that will affect your ability to single source without burdening writers?

    Read more

    DITA Training and Support

    DITA Training

    Learn DITA best practices and make the most of your DITA implementation

    Method M provides end-to-end support for organizations moving to successful DITA implementations. Our services include training in DITA best practices for writers and editors, information architecture, DITA specializations, conversion to DITA, and publishing support for PDF, web, mobile and custom formats. Read more

    oXygen Author and oXygen Developer

    logo_oxygenMethod M supports an array of tools for technical authors, including oXygen Author and oXygen Developer. Method M supports your writers with best practice training, templates, customizations, XMetaL macros, implementation coaching, and much more.

    XMetaL Author

    xmetal logoApply best practics for XMetaL Author. Learn how to use maps, topics, elements, attributes, customizations, macros, automation and much more. Learn the best methods for single sourcing in XMetaL. Choose the functionality that will deliver the best results for your environment, including conref, keyref, and conkeyref.

    Method M DITA Consulting

    Considering a move to DITA-based publishing? Backed by years of experience, we guide your project to successful implementation. Whether you need training for your team in DITA, or in using DITA editors such as oXygen or XMetaL, need information architecture to help you succeed, or help customizing your deliverables – we are here to help. Read more

    Method M DITA Workshop

    The DITA workshop will equip you to evaluate, plan and start implementing the Darwin Information Typing Architecture (DITA). In this workshop you will learn: How to author topic-based, well-structured technical information. How to assemble and publish delivery documents from topics. How to evaluate your needs and choose from standard DITA information types (concept, task, and reference). Plan […]