All the tools presented here are FOSS (free open-source software). If you are a director of IT with a budget that needs to be burned through by the end of the fiscal year and you have no need for high-gloss brochures with more images than text to be printed on paper, why not spend it on the salaries of some qualified technical writing staff, instead of paying for Adobe InDesign? Taking software engineers or administrative assistants off task to use costly typesetting systems for producing rudimentary documentation of back-end software to be consumed primarily online is not a wise business decision.
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.
AsciiDoc is not an application, it is a markup language that is supported by a new generation of agile technical writers who espouse a concept of focusing on the writing process instead of getting dragged down a rabbit hole by the distractions of formatting icons, buttons, check boxes, and menus for formatting.
This widespread markup language provides more formatting and functionality than
Markdown, but is much easier to use than 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.”
A hackable text editor for the 21st Century
Every software developer has their own favorite editor or IDE. I have used
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. This site you are on right now was generated by Jekyll.
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.
Well, Postman might not be FOSS, but it does have a pretty functional free version. For any technical writer specializing in API documentation, it’s highly recommended that you use a tool like Postman that will allow you to test API endpoints which use request body parameters, as opposed to path parameters or query string parameters.