Dan Allen and Sarah White: Documentation Dearth Dooms Open Source Projects

By Jack M. Germain 09/24/14 6:04 PM PT

One of the essential draws to open source software should be superior product documentation. Well-written user guidelines are a key strategy that software developers should use to increase an open source project's growth and user adoption.

All too often, programmers finish their last line of code and shove the open source software out the door -- or, more realistically, post it on their website waiting for users to flock to its greatness. Documentation is often an afterthought -- or the software developer does not think about it at all.

A pair of open source entrepreneurs are determined to help software developers solve the problem of poorly done or missing documentation. Dan Allen and Sarah White are coleads of the Asciidoctor Project and cofounders of OpenDevise. Allen is a software developer and community catalyst; White works on the documentation for the Asciidoctor project.

Dan Allen

Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook 5 (or 4.5) and other formats. Asciidoctor reads and parses text written in the AsciiDoc syntax. It feeds the parse tree into a set of built-in templates to display the content. Asciidoctor is hosted on GitHub and is released under the MIT license.

OpenDevise is focused on providing developers with a strategy and development plan for open source projects. The idea is to help developers and users communicate with each other. The Asciidoctor Project is an effort to bring a comprehensive and accessible publishing tool chain, centered around the Asciidoc syntax, to a growing range of ecosystems, including Ruby, JavaScript and the JVM.

White spoke this summer at the Open Source Conference (OSCON) about the integration of Asciidoctor and OpenDevise and techniques for writing documentation that satisfies users. Her strategies help software developers plan and write documentation without feeling overwhelmed.

Sarah White

In this exclusive interview, LinuxInsider discusses with Allen and White the role these two open source projects play in writing documentation that takes into consideration users needs, backgrounds and environments.

Read this article:
Dan Allen and Sarah White: Documentation Dearth Dooms Open Source Projects