Why Use Markup Languages for Software Documentation?


Lois Patterson


May 4, 2016 - 2:00 PM


May 4, 2016 - 3:00 PM

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.


Career Center

Find your next job/contract opportunity here! Look at the STC Job Bank and get 14-day advance access to the newest employment opportunities.


Access to our industry-leading publications: Intercom, Technical Communication journal, STC’s Notebook blog, newsletters, and the Body of Knowledge (TCBOK).


The educational opportunities that STC members gain access to offer a breadth of continuing education knowledge in a variety of formats including webinars, online courses, Summit sessions, and more.


Leverage the power of members from around the world. Build relationships, advance your career through STC’s global community of technical communicators.


Society for Technical Communication
Phone: +1 (703) 522-4114 | Fax: +1 (703) 522-2075
3251 Blenheim Boulevard | Suite 406 | Fairfax, Virginia 22030
Email: STC | Map it!


The Society for Technical Communication advances technical communication as the discipline of transforming complex information into usable content for products, processes, and services.