Writing documentation with Asciidoctor

Status:
Accepted

AsciiDoc is a lightweight markup language (like Markdown or Textile). Asciidoctor is a comprehensive, user-friendly publishing toolchain for the AsciiDoc writing format. We have decided to use it to reduce the pain when writing documentation and to be more efficient. The asciidoctor platform is easy to use, extensive and open-source. We believe that this tool can help you as it did for us and that is what this talk is about.

What is the ideal platform to write documentation? Because of the numerous solutions, we had to define requirements:

* Good reading experience: multiple outputs formats (pdf/html)
* Modularity: ability to combine and to reuse text blocks across different documents (book, tutorial, training support…)
* Source code snippets: we want to keep them in synch with our codebase.
* Maintainability for across multiple releases.

Over the years we have tried several documentation approaches. We started with a word document (at the beginning of the project). Then we put our documentation content in a wiki engine. We also wrote some of our documents using LaTex, before switching to Asciidoctor. This talk is about sharing the lessons we have learned.

We are developers and some tools are already part of our daily toolbox (Text editor, Git repository…). We have also a lot of best practices: do not repeat yourself, share code, and automatize repetitive tasks. Our vision is that writing documentation should be very similar than writing source code.

In this talk I will present our Asciidoctor toolchain in action and show how our documentation objectives are met. I want to focus on the key points that make us efficient when we work on documentation.

Slides

Comments