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

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 co-leads 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 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 toolchain 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 integrating Asciidoctor and OpenDevise and techniques for writing user-satisfying documentation. 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.

LinuxInsider: Why is making good user documentation often an ignored part of an open-source software project?

Sarah White: Everybody is busy trying to balance their time between programming and the rest of their lives. Programmers are not trained in writing documentation. Writing documents, frankly, can be intimidating. Programmers may be fabulous at writing code — but when it comes to explaining it to different types of users, from advanced to beginner, code writers often feel out of their league.

Dan Allen: I can understand the programmer’s dilemma about writing documentation. It can be a long and painful process. Documentation in open source is often a missing link. There are four major pillars of developing open-source software. Each one has its own elements of problem-solving associated with it. These are design, code writing, testing, and documentation.

Any one of those pillars is no less important than any of the others. Certainly, the documentation aspect is the one that most times gets shortchanged. The tendency for software developers is to look at software code as a vehicle for adding more features. The emphasis is not telling how to use it.

How do you get programmers to deal with the documentation issues?

White: It is sort of like taking the mystery out of writing for the programmer. For the user, the perspective changes. Depending on the skill level, all that might be needed is a quick guide to explain what the basic program functions are and how to access them. So I try to come from both sides.

I try to help developers or whoever in the project support chain is just stuck with the writing. I also try to build a bridge to the users so they can communicate with the project leaders. Sometimes, users just need a basic tutorial rather than a huge user manual. Documentation should not be a mystery. It should not be intimidating for the users or for the people writing it.

Allen: What we have done with Asciidoctor is make the documentation something of value. We do that by, number one, rewarding the writer. For most open-source software developers, whatever documentation is created gets published on the website. So, we show the developer how the content looks on a Web page displayed in Asciidoctor. When the software developer sees how minor the content is, that triggers motivation to fill in the gaps.

So, seeing the documentation displayed motivates the software developer to focus on it just as he or she focuses on writing code?

Allen: Yes. Our experiences in the community have proven this to be an effective strategy. We also discovered early on in developing Asciidoctor that adding an icon library furthers this motivation. It gives the software developer a visual appeal to show headings and other content items, helping them visualize their writing structure. Later in the process, we can pull those icons out.

How have programmers responded to being nudged into writing or improving their documentation?

White: So far, their response has been stunning. We set up OpenDevise in November. We have been overwhelmed with clients who have been really interested in creating better documentation or even some documentation. They have had an interest in improving their home page information and their training materials. I consider all of those elements documentation.

Allen: One of the big realities for the software developers was that their documentation was really a mess. In many cases, this motivated them to start the documentation from scratch. Once they saw the process through Asciidoctor, the developers were willing to address their documentation problem head-on. Some of them asked what we could do to fix the missing documentation problem. Then, they actually made the decision to start over and do it themselves.

How much of a connection exists between the programmers’ completion of documentation and the users’ access to it?

White: Asciidoctor holds tightly to the concept of making documentation portable. It does not tie the documentation to a set format such as PDF or .doc file. The goal is to keep the content separate from what you use to display it. This keeps the display output clean. It avoids the lockout that would otherwise set in with newer technology five years from now. OpenDevise received funding to develop display converters that tie in with Asciidoctor.

Allen: Our goal is to get all software developers to recognize that missing or weak documentation is a big problem for the success of their projects. We want users to come to open source not only because it is the best software. We want users to come to open source for the best documentation for using software.

Where do you see this documentation development process going?

White: From a technology standpoint, our goal is to have a community-driven integration of Asciidoctor with other development and writing toolchains. The goal is to improve integration and the display converters. For example, one of the elements I discuss with clients is avoiding documentation that does not render well on small screens or the mobile experience.

How much of an issue is mobile screen displays?

White: I hear developers say that no one will ever read their documentation on a mobile phone. I really disagree with that view. In five years, everyone will want to do everything on a mobile phone. For some, it will be the only device that they have.

Either way, the devices will be that powerful. Developers will be building and displaying from mobile devices. So why not read the documentation on a mobile phone? Why eliminate a large portion of your potential user base from having access to your documentation? That is another area where Asciidoctor comes into the integration. So, it is not just about having better documentation. It is all about having portable access to it.