Every developer has had to deal with the struggle of sifting through documentation that is incomplete, incoherent, outdated, or simply non-existent. Whether it’s libraries, frameworks, or platforms, the presence of good documentation can mean the difference between success and failure. The absence of good documentation is a serious enough downside to justify avoiding a certain technology altogether.
Sometimes, however, it’s necessary to use a poorly documented piece of software, and we just have to make the best of it. There are a few things you can do to make it easier to make progress when answers are hard to find.
The main difficulty lies in piecing together information from a variety of sources rather than having one source of truth. You’ll also have to adapt to the reality that progress is going to be slower and harder fought. There’s going to be a lot of trial and error, guessing and checking, and a lot of time spent in the debugger.
Here are my suggestions to make it less painful.
1. Check the Code for Comments
For projects with little to no documentation, you can often find an abundance of comments added by the developers in the actual source itself. Reading these is no substitute for good documentation, but they can sometimes provide valuable insight into the authors’ thought processes.
Library authors often think a lot about API design in an attempt to provide consistency across all areas of their code. For example, if you pass a callback into a function in Express, you can almost always assume that the first argument is going to be the request, and the second is going to be the response. In a Lodash iteration function, the first argument is always going to be the value, and the second will be the key, the index, or some other piece of information.
When someone is very familiar with a well-designed library and learns of a new piece of functionality, they can often guess exactly what it’s going to be named and exactly how it’s going to be used. This is one of the aims of good design, and many authors strive to make it possible.
Usually, these design philosophies and patterns emerge in the documentation, but even if they’re not documented, they can sometimes be gleaned from code comments and extrapolated to the rest of the library. When you’re reading comments in poorly documented code, try to pick out places where the author may be describing a design decision that could apply to other areas of the codebase.
Once you’ve discovered a few of these patterns, it’s a lot easier to make educated guesses. This can help when you’re trying to figure out which parameters do what or how a particular function may be named.
2. Learn How to Read Outdated Documentation
Sometimes, the quality of documentation for a given piece of software declines as its popularity rises. In the beginning, good documentation can be a way to spur adoption. As the project becomes more and more popular, there is less of a need to hook developers with good documentation. If you find yourself in a situation like this, looking at old documentation can help.
Even though a library may change significantly over time, the authors will often try to keep the usage patterns consistent to help users adapt to the changes. You have to make sure the current version isn’t a radical departure from the old versions, and you have to take everything with a grain of salt. Remember that you’re looking for broad usage patterns rather than specific examples. Some examples may be identical, but don’t count on it.
3. Search IRC, Newsgroups, and Mailing Lists
If you’re dealing with something old, you can find a wealth of information in mailing lists, newsgroups, and archives of IRC channels. Yes, people are still using these—and they’re still in heavy use for stuff that’s been around for a while. Information from these sources will sometimes appear near the top of a Google search, but not always. You will usually have better luck searching the archives directly for whatever you need.
It’s not a bad idea to subscribe to a mailing list, too. You never know when you will run into a problem that you saw discussed in a recent email chain.
Here are a few good sites to search the archives of popular lists:
https://marc.info
http://vger.kernel.org/vger-lists.html
https://www.mail-archive.com
4. Search GitHub for Usages
If you’re trying to see the way a particular class or function is used, you can search its name on GitHub to find open-source projects where other people are using it. This is one of the easiest ways to find a ton of examples of people using whatever it is you’re trying to figure out.
These four tips have helped me navigate difficult pieces of code with ineffective documentation. What are your strategies for tackling poorly documented code? Drop them in the comments below!