Document 360: #1 Knowledge Base Software
Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,400+ subscribers

Search results

Document 360: #1 Knowledge Base Software

Why developers will never adopt DITA

by Tom Johnson on Sep 30, 2014 •
categories: api-docdita

Ever wonder why developers resist DITA so much? Take a look at this comparison. Here are two ways to describe a simple task of printing a page.

DITA syntax

<task id="task_mhs_zjk_pp">
    <title>Printing a page</title>
    <taskbody>
<steps>
        <stepsection>To print a page:</stepsection>
    <step>
        <cmd>Go to <menucascade>
            <uicontrol>File</uicontrol><uicontrol>Print</uicontrol>
        </menucascade></cmd>
    </step>
    <step>
        <cmd>Click the <uicontrol>Print</uicontrol> button.</cmd>
    </step>
</steps>
    </taskbody>
</task>

Markdown syntax

## Print a page
1. Go to **File > Print**.
2. Click the **Print** button.

Conclusion

Granted, I'm simplifying things a bit. DITA allows you to re-use text, apply attributes, and process your content into more than just HTML.

But if you're just publishing to the web, and you don't have a lot of complex re-use requirements, isn't it just extra work adding all of these DITA tags?

What it means for tools

A lot of vendor energy has been spent in simplifying DITA. For example, there are ways to create DITA using interfaces that look just like Microsoft Word. However, simplifying DITA through easier authoring interfaces isn't really the problem. The problem is that developers build tools that accommodate simple authoring models. Nearly every developer tool for API documentation, such as Slate, API Blueprint, Doxygen, Nanoc, Github, and Docco all use Markdown instead of HTML or XML for authoring.

I don't foresee developers going out of their way to accommodate DITA processing in the API doc tools they build. Instead, DITA will most likely need to provide transforms that allow content to be pushed into these API toolsets. That may mean creating a DITA-to-Markdown transform, which isn't something any XML professional is going to want to do given that Markdown would remove much of the complexity and power in publishing.

The divide between tech comm tools and API doc tools will continue to be difficult to bridge.

Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,400+ subscribers

follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer based in the San Francisco Bay area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.

Comments