briandominick

Why Use AsciiDoc for Software Documentation

I have now spent a decade convincing engineers and technical writers to use AsciiDoc markup for as much of their product documentation as is humanly possible. Few if any of them have regretted adding AsciiDoc to their skillset or switching to it entirely, so now I hope to make the case for a general audience.

This article collects the arguments I have long used to help writers and software developers see that AsciiDoc is far and away the optimal solution to nearly all documentation matters beyond API docs (where more structured approaches are called for).

For anyone using docs-as-code workflows and free, open-source software, the main competitor for AsciiDoc is Markdown, which many developers love and swear by. For this reason, I will compare/contrast AsciiDoc and the collective flavors of Markdown.

briandominick

Software Documentation Tooling Decision Guide

The following are my suggestions regarding what else to consider for each of Daryl White’s excellent questions about choosing a toolset for documenting a software product or project.

I have appended a brief guide to the main/broad categories of documentation toolsets and some of the platforms/components that are popular in each.

Finally, this resource ends with a table of possible solutions for various scenarios you might find yourself in.

Before we start with the existing list of questions, I want to highlight one that I think is most important of all, but which is often assumed by people who create these kinds of guides, as they tend to come from one or another world already.

briandominick