Open Source

Open source documentation is bad, but proprietary software is worse

Open source gets a lot of stick for its poor documentation, but developers still prefer it to proprietary alternatives.

Image: iStockphoto/opolja

That shiny new developer job is going to involve a lot of rusty old codeOpen source keeps growing from strength to strength despite the vast majority of developers not bothering to document how any of it works. That's one big conclusion from GitHub's 2017 survey, in which 93% of respondents gnashed their teeth over shoddy documentation but also admitted to doing virtually nothing to improve the situation. Indeed, while many may nod their heads when Apache Storm founder Nathan Marz intoned that "Documentation is essential" to a successful open source project, few bother to pitch in.

And source marches on, with no signs of slowing anytime soon. If documentation matters so much, why hasn't open source adoption been impeded by its alleged crappiness?

Documentation? I can't be bothered

Ask a developer what her primary gripes with open source are, and documentation gets top billing, and by a wide margin, as the GitHub survey reveals:


Indeed, the top three responses all involve "documentation" in some form, with 93% initially frustrated with the quality of documentation and then large majorities also calling out the unresponsiveness of project maintainers (roughly 80%) or rude responses (nearly 60%) to questions likely asked in the wake of that inability to get answers from documentation. If you think this deeply felt need for documentation would motivate more developers to pitch in and help, you'd be wrong: 60% of developers can't be bothered to contribute documentation.

SEE: That shiny new developer job is going to involve a lot of rusty old code (TechRepublic)

iOS developer Jeff Campbell called out this open source omission, declaring: "Docs are too often an afterthought in the open source world." Perhaps this is because, following author Steve McConnell's direction, many developers believe that "good code is its own best documentation," and, of course, assume their code is very good.

Whatever the reason, the effect of poor documentation is to lock out would-be users of that software, especially women, as the GitHub survey authors note: "Documentation that clearly explains a project's processes, such as contributing guides and codes of conduct, is valued more by groups that are underrepresented in open source, like women."

Not that documentation is the only issue. As Navica CEO Bernard Golden told me, "There are plenty of other drawbacks to open source besides poor documentation. It shines in code availability and (some) openness to contributions. In areas like documentation, integration, support, and quality control/testing it has extremely high variability" from project to project. Some projects are great in each of these areas Golden calls out, and many (most?) are not great.

And source has never been more popular.

The alternative is worse

While lack of documentation is bothersome, it's not fatal, as developer Ted Wise indicated to me: "Code is still usable without docs. Barrier to entry is higher and some capabilities may be obscured, but still usable." Or, as Google lead product manager Vanessa Harris stated: "Outcomes matter more than documentation." Those outcomes are more easily come by with open source, given the lowered barriers to using and writing software.

Plus, it's not clear what "bad documentation" even means. As professor and former Joomla! developer Elin Waring said to me: "[Y]ou can read the code and automated docs. When people complain about docs it is not always clear what they mean".... She went on: "Different people need different docs, [which is] why 'everyone complains about docs' is so hard to respond to. It's a constantly moving target."

Hence, it may be true, as Puppet founder Luke Kanies wryly observed that "[open source is] the worst thing out there, except for all of the others."

Is proprietary software *that* bad?

To Kanies' point—and to a follow-up question that Golden highlighted to me in text exchange, "What are the drawbacks to proprietary software that are so unattractive that people flock to use poorly-documented open source?"—proprietary software companies seem to be responding with the cloud. After all, if the primary allure of open source is immediate gratification—want code, get code—then cloud computing perfects this availability by opening access to running code, and not merely its potential.

SEE: Why AWS Lambda could be the worst thing to happen to open source (TechRepublic)

Developers crave convenience, something that both open source and cloud can deliver in spades, and which traditional software quite simply fails to deliver.

Python expert Matt Harrison said it this way: "I can go try open source without any commitment or hassle." That hassle? According to Kanies, it's "the need to ask permission." Developers, in short, are willing to give up the added productivity that better documentation affords in exchange for unfettered access to code or APIs, as the rise of cloud computing demonstrates.

That convenience can cover a multitude of documentation sins. So the next time you hear a developer complain about poor documentation, ask her if it's stopping her from using that software. Odds are good that she'll answer, "Are you crazy? And have to ask Purchasing to get me a license to use Proprietary Product X?" Convenience is more compelling than docs.

Also see

About Matt Asay

Matt Asay is a veteran technology columnist who has written for CNET, ReadWrite, and other tech media. Asay has also held a variety of executive roles with leading mobile and big data software companies.

Editor's Picks

Free Newsletters, In your Inbox