Why Use Markup Languages for Software Documentation?

Agile software development workflows require that documentation be developed as part of the product and delivered frequently. If your documents use the same repository as does the code of software developers, then timely integration of docs and code is easier to achieve. Using text-based markup languages for docs facilitates this integration process.

Markup languages can be highly structured, like DITA XML, or lightly structured, like Markdown. We will look at DITA XML, restructuredText, Markdown, AsciiDoc, and others.

We will look at these topics:

• What is a markup language?
• What does “treat docs as code” mean?
• A comparison of markup languages, and benefits and drawbacks of different options (including restructuredText, Markdown, and AsciiDoc.)
• Markup languages and tool choice, in a software development culture where software developers are documentation content developers.
• Markup languages and documentation output (static site generators and more.)
• Migrating from a custom XML documentation system to a Sphinx/restructuredText system–my experience as documentation manager.