# Strong information typing without the XML overhead

<blockquote class="border-l-4 border-indigo-500 pl-4 py-2 my-6 bg-indigo-50/50 dark:bg-indigo-950/20 text-indigo-950 dark:text-indigo-200">
**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.
</blockquote>

<div class="my-6">

</div>

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](https://redaction-technique.org/dita-xml-to-markdown-lightweight-information-typing).

<figure class="my-6">
  ![XML overhead: A cargo ship](https://redaction-technique.org/images/blog/strong-information-typing-without-xml-overhead-large.webp)
  <figcaption class="text-sm text-gray-500 dark:text-slate-400 mt-2 text-center">XML tooling overhead: complex schemas, specialized editors, and build pipelines can weigh down agile documentation teams.</figcaption>
</figure>

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.

## 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](https://docs.oasis-open.org/dita/v1.2/os/spec/langref/step.html) illustrates this rigid nesting:

### DITA Task XML (<task>)

```xml
<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:

| DITA Element | Structural Purpose | Markdown Convention |
| ------------ | ------------------ | ------------------- |
| `<title>` | Topic title | `# Top-level H1 heading` |
| `<context>` | Why/when to perform task | Opening introductory paragraph |
| `<prereq>` | Necessary setup/permissions | Bulleted prerequisite list or callout |
| `<steps>` / `<step>` | Ordered procedure | Numbered list (`1.`, `2.`) |
| `<cmd>` | Mandatory action command | Bold imperative sentence (`Select **File** > **New**`) |
| `<info>` | Explanatory context | Indented sub-paragraph beneath the step |
| `<result>` | Verification of success | Final closing outcome paragraph |

Here is the equivalent task written in standard Markdown:

```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.
```

<blockquote class="border-l-4 border-emerald-500 pl-4 py-2 my-6 bg-emerald-50/50 dark:bg-emerald-950/20 text-emerald-950 dark:text-emerald-200">
**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.
</blockquote>

---

## 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](https://docs.oasis-open.org/dita/v1.2/os/spec/langref/concept.html) demonstrates this explanatory structure:

### DITA Concept XML (<concept>)

```xml
<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:

```markdown
# 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.

<blockquote class="border-l-4 border-amber-500 pl-4 py-2 my-6 bg-amber-50/50 dark:bg-amber-950/20 text-amber-950 dark:text-amber-200">
**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.
</blockquote>

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](https://redaction-technique.org/scalable-maintainable-technical-docs-with-yaml) 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.

<blockquote class="border-l-4 border-blue-500 pl-4 py-2 my-6 bg-blue-50/50 dark:bg-slate-800/60 text-slate-900 dark:text-slate-100">
**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](https://redaction-technique.org/experimental-astro-api-docs) across web and mobile platforms.
</blockquote>

---

## Related reading

- [From DITA XML to Markdown: lightweight information typing](https://redaction-technique.org/dita-xml-to-markdown-lightweight-information-typing) - the migration story and structural trade-offs.
- [From document to modular document base](https://docs.redaction-technique.org/en/formats/modular-documentation/) - foundational DITA concepts behind modular writing.
- [Structured and unstructured formats](https://docs.redaction-technique.org/en/formats/structured-vs-unstructured-formats/) - information-typing reference treatment.

## External sources

- [DITA task/concept/reference typing](https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture)
- [DITA Open Toolkit (the heavyweight it replaces)](https://www.dita-ot.org/)
- [Markdown as the lightweight host](https://en.wikipedia.org/wiki/Markdown)

<small>*Hero image: ["Girders overhead cast shadows on the walls and floor of a support building under construction. Original from NASA . Digitally enhanced by rawpixel."](https://www.flickr.com/photos/vintage_illustration/46313328852) by [Free Public Domain Illustrations by rawpixel](https://www.flickr.com/photos/vintage_illustration/), licensed under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/).*</small>

---

Source: https://redaction-technique.org/strong-information-typing-without-xml-overhead