Article summary
I started my career at Atomic Object about four months ago. During that time, I’ve needed to get up to speed on a tech stack where I only had bits and pieces of experience. I had to learn to navigate a far bigger project than anything I had worked on during my time in college.
Different libraries and parts of my project’s stack had varying levels of documentation, in terms of both quality and quantity. I discovered that, often, it was the open-source libraries put out by smaller teams of developers that presented me with the biggest challenges. In this post, I present some tips for getting familiar with a new library.
Read the Documentation
This tip is a bit of a no-brainer. It’s probably the same one you’ll get from any beginner programming guide. It also happens to be a great tip. A library’s documentation is, hopefully, the author’s best effort at pointing out the important “whats” and “whys” of their library. What problems does the library solve? How do you install it in your project? What does the API look like? What are some examples of its usage?
However, there are some pitfalls involved in documentation. One speed bump I hit was looking at documentation for the wrong version of a library. I was looking with frustration at one screen showing my code, and another with library documentation—completely confused about why the two didn’t align. Sometimes, I remedied the problem by tracking down the library website’s version dropdown. Other times, however, the up-to-date documentation simply wasn’t published. This leads to my next tip.
Read the Code
In the words of Ron Jeffries, “Code never lies, comments sometimes do.”
In a way, documentation is a project-wide comment. Comments can grow stale, be confusing, or fail to accurately capture the intent of the code they describe. Documentation can suffer from the same pitfalls.
Sometimes, after reading through a page on a project’s API, I found myself more confused than when I started. But hopping into the code brought clarity through just a few lines. Other times, reading through the code itself exposed small bugs in the project or places where the code didn’t behave quite the way the documentation said it did.
Most importantly, though, reading through the source code of open-source projects is a learning opportunity in and of itself. Reading code is often harder than writing it, and any chance to sharpen that skill is worthwhile. Also, it exposes you to more than just your team’s code and gives you a chance to see how someone else approached a problem.
Pay Attention to GitHub
Finally, pay attention to the project’s GitHub repository. Getting used to moving around GitHub repos is an invaluable skill for using open-source projects effectively.
Often, looking through a project’s repo solved the problem of unpublished or out of date documentation. Projects usually have readme files or directories of documentation that are more up-to-date than the project’s website.
Other times, projects are simply too small to warrant a full website, so their GitHub repository is the single source of project info.
Most important, though, is the context a GitHub repository provides via issues and pull requests. Many times throughout the past few months, I have found solutions to the same problems I had in the issues tab. Issues and pull requests provide a place for interaction with the project’s authors.
Conclusion
When you’re getting up to speed on a new open-source library, the key is reading. Read any and every resource the authors provide, from documentation to GitHub comments to the source code itself. When you’re reading, prioritize material that gets at the intended usage, like examples and tutorials. And, for an extra learning boost, don’t be afraid to go straight to the source.