Choosing the Right Documentation Management Approach: DITA XML vs. Docs as Code

DITA XML and Docs as Code are two different approaches to managing and authoring documentation.

DITA XML (Darwin Information Typing Architecture) is an XML-based markup language. When writing in DITA, you use structured authoring to create modular content. Structured authoring means that there are rules in place to ensure information is organized consistently. The modular approach allows you to assemble topics and elements and publish them in several formats. DITA supports concept, task, and reference information types. When writing, you select an information type to create a topic, which can be reused. This makes translation and localization more efficient. You create a map to specify the topics to be included in a deliverable. 

Docs as Code is a philosophy that supports writing and managing documentation with the same tools as code. Typically, you write in a lightweight markup language like Markdown or Asciidoc, manage the files in a version control system like Git, perform code reviews, and can use issue trackers and automated tests. The output is built using static site generators (SSGs) like Gatsby and Docsaurus. A benefit of Docs as Code is that it fosters collaboration across departments such as engineering, product, and technical writing. Another benefit is continuous integration/continuous deployment (CI/CD). For example, you can run automated checks on your documentation using linters such as Vale. If the documentation passes the checks, it can be merged and published immediately.

I have used both DITA XML and Docs as Code and have found that both approaches have their pros and cons. I know there are folks with opinions on this and would love to hear your thoughts!

See post on LinkedIn.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s