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 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

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

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 in having to write 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 it 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.

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


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 software developers of open source software, whatever documentation that 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.

LI: So seeing the documentation displayed serves to motivate the software developer to focus on the documentation just as he or she focuses on writing code?


Yes. Our experiences in the community have actually 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. This helps them to visualize their writing structure. Later in the process we can pull those icons out.

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


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.

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


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.

LI: Where do you see this documentation development process going?


From a technology standpoint, our goal is to have a community-driven integration of Asciidoctor with other development and writing tool chains. 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.

LI: How much of an issue is mobile screen displays?


I hear developers say that no one is ever going to 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 having better documentation. It is all about having portable access to it.

Jack M. Germain has been writing about computer technology since the early days of the Apple II and the PC. He still has his original IBM PC-Jr and a few other legacy DOS and Windows boxes. He left shareware programs behind for the open source world of the Linux desktop. He runs several versions of Windows and Linux OSes and often cannot decide whether to grab his tablet, netbook or Android smartphone instead of using his desktop or laptop gear. You can connect with him onGoogle+.


  • Colleagues,

    I currently work as a freelance Technical and Business writer. I could not agree more with your analysis of the "Documentation Dearth." Please tell me how I might join in and contribute to YOUR efforts to create good documentation for open source (FLOSS) projects.

    I have some observations and insight from my own efforts and career. I worked as a software developer for over 30 years until "retirement." Where might I direct my writings on this topic for your review? I find that too many folks completely dismiss postings and other writings about documentation. Your recent "Dearth" article contains many of the reasons why this is the case. There are other reasons.

    ~~~ 0;-Dan

  • Most Open Source projects do not have any systematic way for WRITERS to ask questions and get answers about the software. Frequently, a WRITER must resort to black-box testing [little or no access to the application internals] techniques hoping to discover what the software does. This explains why so much of what claims to be documentation is little more than an inventory of forms and fields and buttons and menus. These get padded with screen capture images and wrapped in prose that says, "… I poked it and this is what happened …"

    Of course it is useful when the programmers embed descriptive information into the code itself. It is even more helpful when there are tools to extract and format this information for easy consumption. However, I experienced embedded information that is most useful to other programmers and only marginally useful to an end-user. For real, end-user value, one needs a WRITER first and foremost. I trained to be such a WRITER.

    I worked over 30 years designing and writing code and documentation to support it. WRITERS most often cannot (or do not want to) read code to discover detailed information about software. They must have access to subject matter experts.

    I can read the code and other developer materials and I have tried without success to contribute documentation into several projects in the Linux(tm) ecosystem. Code reading takes huge amounts of time to have confidence that one understands what one is reading. It often requires more time and effort investedd in tool chains along with project and developer workflow.

    A primary difficulty lies with the lack of access to experts for detailed questions and honest dialog. Just as "programmers" see those who write device drivers as a breed apart, so too must Open Source project embrace WRITERS as another different breed with their own needs supporting successful documentation.

    I am ready and willing to contribute my prose to projects who support their WRITIERS with access to information and folks who can and will answer questions under some reasonable project process.

Leave a Comment

Please sign in to post or reply to a comment. New users create a free account.

More by Jack M. Germain
More in Exclusives

LinuxInsider Channels