By using AsciiDoc, you're already following one of the best practices we recommend. You can write once and publish everywhere!AsciiDoc takes a lot of the pain out of writing documentation and keeps it DRY. As with any tool, you need to learn the best practices to use it effectively, such as:How to organize your documentationHow to make your documentation approachable to contributorsHow to make your documentation easy to maintainWhat tools to use to simplify collaboration & maximize reuseI'll address some of the challenges we've come across writing documentation in AsciiDoc, offer a set of tips and recommendations that have helped us improve our writing flow and provide advice about how to keep presentation from leaking into your content...and why it matters.
Authors:
Dan Allen
Dan is an open source advocate, community catalyst, developer, published author (Seam in Action) and internationally recognized speaker. He is the lead of the Asciidoctor project (asciidoctor.org), serves as the strategic advisor for Arquillian (arquillian.org) and helps promote the JVM as a polyglot Java Champion.
As one of the founders of OpenDevise, Dan works with software communities and businesses to help them discover and cultivate their open source way. (Is there any other way?)
After a long conference day, you'll likely find Dan enjoying chatting about tech, docs and open source with fellow community members over a Trappist beer or Kentucky Bourbon.
Maxime Gréau
Software Factory Manager @ eXo Platform