Tools
Taking software engineers or administrative assistants off task to use costly typesetting systems designed primarily for graphics-centric marketing content in order to produce rudimentary software API documentation for online consumption is not a wise business decision.
Git
Long before Git became mainstream, most software developers worked with CVS. By the early 21st century SVN, now known as Apache Subversion, was dominant until April 2005 when Git, and 12 days later, Mercurial with a very similar feature set, emerged as a completely new, distributed RCS systems. Suddenly branching and merging were no longer painful processes and there was no “central authority!” Everyone could live in their own little world of code, happily committing code changes offline while riding BART on the way into San Francisco every morning. It was a major paradigm shift.
As a software developer, team lead and manager of our small software team I switched us over to Git in 2012 and never looked back. Coupled with the value added by GitHub, integrating technical writing projects into a private Git repository hosted by GitHub where team access can be easily administered, this platform has become the norm for many technical writing teams. Now that I have been working with GitLab, I find that merge requests play an integral role in the document creation/maintenance and review steps of our technical documentation workflow.
AsciiDoc
AsciiDoc is not an application.
It is a markup language that is supported by a new generation of agile technical writers who prefer focusing on the writing process instead of being constantly distracted by the need to switch gears and grab for the mouse for simple tasks like text formatting or creating a new section heading.
This widespread markup language provides more formatting and functionality than Markdown, but is much easier to use than LaTeX.
Atom
A hackable text editor for the 21st Century
Every software developer has their own favorite editor or IDE. I have used vi, Coda, GNU Edit, PhpStorm, and Atom. For general text editing, JavaScript, HTML, and markup languages, I prefer Atom. A wealth of plugins exist for Atom, including a very nice AsciiDoc previewer.
Visual Studio Code
Visual Studio Code is an alternative to Atom.io, especially if you intended to work with Microsoft Azure on a regular basis. It supports AsciiDoc and has many features that make it an appealing choice for any technical writer or software developer.
Antora
For designing AsciiDoc-based docuemtation sites, there’s really nothing that can currently compete with Antora based on its rich set of features:
-
It supports documentation versioning.
-
All AsciiDoc content, images, code examples, and attachments can be remotely stored, e.g., in GitHub, GitLab, or any privately managed server functioning as a remote Git repository.
-
It uses a compressed UI bundle sandbox for developing custom CSS layouts. A Git repository containing the default Antora UI can be cloned and customized. The repository provides a sandboxed environment for creating and testing your CSS customizations.
-
It scales well for larger sites having multiple sets of technical documentation.
-
This framework was created by, and is actively maintained and supported by, the creators of Asciidoctor.
Jekyll
Jekyll is like WordPress without PHP and without MySQL. In other words, it is super fast, can scale much larger than WordPress or any other blogging system that is bogged down by a back-end scripting language and database queries. It is a basic, no-frills framework for creating a blog site that allows technical writers to use AsciiDoc for writing their blog posts.
Jekyll takes Markdown or AsciiDoc plain text files and converts them to raw HTML files that can be served by its own webserver engine, or by an even faster webserver like Nginx.
LaTeX
\(\LaTeX{}\), written by Leslie Lamport as a simplified, easier to use markup syntax for the highly complex and difficult to use TeX typesetting system. Lamport’s goal was to provide the essentials for writers who want to focus on content while the TeX back end handles the layout of the final publication. LaTeX was first released in 1983 and has become, according to its official website, “the de facto standard for the communication and publication of scientific documents.”