Strong information typing without the XML overhead

Core premise: DITA’s lasting value is not its verbose XML syntax or heavy tooling pipelines—it is the mental discipline of information typing. Classifying content into tasks, concepts, and references creates clear, predictable documentation, a practice that thrives in lightweight Markdown and docs-as-code workflows.

If you’ve spent years working daily with the DITA XML platform, you know that DITA is far more than an angle-bracket markup language. It is a way of thinking about information design. Writing tasks, concepts, and references in DITA trains you to deconstruct documentation into modular, predictable building blocks. For background on how this site migrated from DITA XML to Markdown while keeping those principles intact, see From DITA XML to Markdown: lightweight information typing.

The good news is that you don’t need an XML editor or a bulky DITA-OT pipeline to practice those principles. With Markdown and modern docs-as-code workflows, technical writers can apply DITA’s information typing philosophy in a lightweight, flexible, and developer-friendly environment.

The DITA mindset: Three core questions

Before typing a single line, the DITA mindset trains technical communicators to classify content according to user intent:

Once you’ve internalized this classification, it becomes second nature to apply outside XML. Markdown pages, Git-based repositories, and static site generators all become vastly easier to navigate when you keep these three categories structurally distinct.

DITA-like task pages

DITA task topics enforce a strict internal sequence: short context, prerequisites, ordered steps, and expected results. The official OASIS DITA task example illustrates this rigid nesting:

<task id="sqlj">
  <title>Creating an SQLJ file</title>
  <taskbody>
    <context>Once you have set up SQLJ, you need to create a new SQLJ file.</context>
    <steps>
      <step>
        <cmd>Select <menucascade><uicontrol>File</uicontrol><uicontrol>New</uicontrol></menucascade>.</cmd>
        <info>New files are created with default values based on a standard template.</info>
      </step>
    </steps>
  </taskbody>
</task>

The diagram below illustrates the hierarchical element tree that DITA enforces inside a task topic:

Mapping DITA task structure to Markdown conventions

Markdown does not have native <task> tags, but disciplined writers can replicate the exact same structural hierarchy using clean typography and formatting conventions:

Here is the equivalent task written in standard Markdown:

# Creating an SQLJ file

Once you have set up SQLJ, you need to create a new SQLJ file.

1. Select **File** > **New**

   New files are created with default values based on a standard template.

The core realization: The XML vocabulary changes; the underlying information architecture remains intact. By respecting the distinction between action commands and explanatory context, your Markdown tasks stay focused, scannable, and predictable.

DITA-like concept pages

Concepts answer “what” and “why” rather than “how.” Where a task demands sequential numbered steps, a concept builds understanding through definitions, comparisons, and background explanations.

The official OASIS DITA concept example demonstrates this explanatory structure:

<concept id="concept">
 <title>Introduction to Bird Calling</title>
 <shortdesc>If you wish to attract more birds to your Acme Bird Feeder,
learn the art of bird calling. Bird calling is an efficient way
to alert more birds to the presence of your bird feeder.</shortdesc>
 <conbody>
   <p>Bird calling requires learning:</p>
   <ul>
    <li>Popular and classical bird songs</li>
    <li>How to whistle like a bird</li>
   </ul>
 </conbody>
</concept>

In Markdown, you signal that you are writing a concept by structuring the page around definitions, bulleted characteristics, and conceptual models rather than imperative action verbs:

# Introduction to Bird Calling

If you wish to attract more birds to your Acme Bird Feeder, learn the art of
bird calling. Bird calling is an efficient way to alert more birds to the
presence of your bird feeder.

Bird calling requires learning:

- Popular and classical bird songs
- How to whistle like a bird

The absence of numbered step instructions immediately communicates to the reader that this is background knowledge, not an execution procedure.

Why DITA information typing still matters in Markdown docs

DITA XML can feel heavy and cumbersome in modern web documentation pipelines. But the discipline you develop after years of practicing information typing doesn’t vanish when you move to Markdown—it becomes your greatest competitive advantage.

By bringing DITA’s principles into lightweight environments, you:

• Keep content modular and reusable: Independent topics can be referenced, embedded, or reordered without narrative entanglement.
• Eliminate cognitive ambiguity: Readers immediately know whether they are following instructions, absorbing architecture, or looking up reference facts.
• Streamline writer onboarding: New team members write against clear structural templates rather than staring at a blank page.
• Make docs automation- and AI-ready: Predictable topic boundaries make documentation significantly easier for static site generators, search indexes, and AI language models to parse and synthesize.

Discipline vs. schema enforcement: In DITA, an invalid task topic without steps fails DTD/XSD compilation. In Markdown, syntax never complains if a task lacks steps or a concept secretly hides a procedure. For small teams, internalized discipline is often enough; for larger organizations, teams recreate lightweight guardrails using frontmatter (type: task), linting rules, and automated CI validation.

DITA taught technical writers to think in information types, not just sprawling chapters. Markdown allows us to practice that thinking with dramatically lower operational overhead, using open tools that integrate smoothly into modern software development workflows. For reference data, YAML as a single source of truth provides the exact same structured rigor.

If you’ve worked in DITA for years, don’t view that experience as outdated. The information-typing discipline you mastered is the single most valuable foundation for building smarter, cleaner, and more maintainable docs-as-code repositories today.

Related architectural pattern: The same structured content philosophy extends to reference datasets. See how one YAML file powers build-time tables and live API documentation across web and mobile platforms.

Related reading

• From DITA XML to Markdown: lightweight information typing — the migration story and structural trade-offs.
• From document to modular document base — foundational DITA concepts behind modular writing.
• Structured and unstructured formats — information-typing reference treatment.

External sources

• DITA task/concept/reference typing
• DITA Open Toolkit (the heavyweight it replaces)
• Markdown as the lightweight host