Programmers Hate Writing Documentation - These 4 Tools Can Help
To facilitate solid documentation, here are the four best online software documentation tools available today.
Join the DZone community and get the full member experience.Join For Free
For the typical programmer, spending hours creating code or repurposing and modifying existing code is just a part of an average day. For the vast majority, it's time spent doing something they truly enjoy. After all, there's plenty of truth in the stereotype of the programmer that shuts themselves off from the rest of the world while busily working on their latest project.
What you won't find as many doing is keeping solid documentation about how their code works. In fact, many programmers seem averse to keeping documentation of any sort. Author and expert on the psychology of programming Gerald Weinberg summed it up by calling documentation "The Castor Oil of programming" – in other words, something that's good for them but that they hate to do.
In reality, this translates into a dearth of information about how various pieces of software work. At best, today's developers are taught to leave a barebones roadmap within the code they write. But that does nothing to remedy the situation for end-users of that code, who often can't rely on the accuracy or utility of whatever user manuals happen to be available for the products they use.
That's why it's important for software developers to develop solid documentation habits so that their black-box code won't be a mystery to everyone else. To facilitate that, here are the four best online software documentation tools available today.
Since there's likely no developer working today that doesn't have experience using the ubiquitous code repository GitHub, it's a natural place to start for programmers looking to keep documentation. Although many only make use of the readme functionality within their codebase to provide a simple how-to for whatever the project does, that's not the only (or even the best) way to create documentation on the popular platform.
That distinction goes to GitHub pages, which provides a dedicated hosting platform for project pages – including documentation and manuals. It interfaces directly with all GitHub repositories, allowing developers to update their documentation in the same way they would update their code. Better yet, users can turn to Jekyll, which can transform their plain-text markdown into full-blown styled static websites with no additional coding needed.
Read the Docs
As the name implies, Read the Docs provides a centralized platform for developers to keep their documentation so users can, well, read it. It works somewhat like GitHub pages, in that developers can push documentation changes from their favorite version control system, including Git, Bazaar, Mercurial, and others. The site even handles automatic page versioning and building, making documentation maintenance a snap.
Possibly the best part of Read the Docs, though, is its flexibility. It supports webhooks, so developers can automate much of the document creation process. It's an enormous time-saver in a task that most programmers want little to do with in the first place. On top of that, everything hosted on the platform is made available to the public in multiple formats, including PDFs, single-page HTML, and even for eReaders. The bottom line is, it's a site that takes much of the drudgery out of keeping documentation up to date.
Although not strictly built as a software documentation platform, but rather as a full-blown knowledge base, Tettra is nonetheless a great tool for software documentation. It works especially well when a project involves a large group of coders working on different parts of the software, and when non-technical users are going to have to understand the ins and outs of what's been completed and what's yet to be done.
For most software developers, Tettra shines brightest when it's used to document the answers to common questions about their work. Using it in that way provides a central repository for managers and other project members to go to find status and functionality information. Every question it answers is one fewer phone call that the programmer has to deal with, and for that alone it should win a place in every developer's heart.
Even though software documentation should be considered mission-critical at all times, there's one type of documentation that no developer can ever afford to skimp on: documenting APIs. Since they're the parts of software most exposed to external users, they're also the ones that generate the most questions and issues when something's not clear. That's where Apiary comes in.
What makes Apiary so useful for developers is the fact that it's more than a place to include static instructions regarding API use. Instead, it's a platform that allows users to write their documentation in Markdown including mock API calls. The platform then allows users to test the API without having to use the software itself or program a real call – which is a feature that developers can also use for the rapid-prototyping of their API designs, to begin with. In other words, it's a documentation tool and a testing platform all in the same place. It couldn't be easier.
No More Excuses
While the documentation tools mentioned here don't make the process of dedicating time to the task any more attractive to developers, they do make things far easier than they would otherwise be. By making the job of keeping complete and accurate documentation something that uses the same tools programmers are already working with, they take many of the standard excuses away for avoiding the extra work.
In the case of Tettra and Apiary, there are even the added benefits of helping programmers avoid the time they waste answering repetitive questions and prototyping APIs. That at least offsets the time they'd be spending documenting their work, making the whole process a net benefit to whatever project they're working on.
However they rationalize it, though, it's obvious that programmers have to do a better job of documenting their work. Now that there are so many easy ways to do so, there's no more room for procrastination. Plus, it's the right thing to do. After all, every programmer has faced the challenge of unraveling someone else's code with little or nothing to go on, so it's only fair that they spare others from the same fate. Just consider it the programmer's version of "paying it forward". No Castor Oil required.
Opinions expressed by DZone contributors are their own.