In late summer of 2007, I had spent a weekend building a prototype of our first product, a carbon calculator. I had built it in Javascript, loaded from a static web page, what is commonly known today as a single-page app, but for me at the time, was just the fastest way to get some functionality on the web. A week later, my teammate built the back-end in Rails, and we had a decent fully functional carbon calculator. We used Google Maps to show flights and the carbon emissions associated with each one. It was my first time using their API, and I needed to draw our own routes and calculate the distances between departure and destination. No problem. I took a quick look at the docs to figure out what functions to call and “Voila!” purple lines overlaid on top of the map showing each flight the user input. Cool. Ship it!
The next week, we started getting reports about it not working right in IE. Of course. I had my boss’s old Windows laptop to test with, and I spent hours and hours and hours trying to debug. It worked great in Safari and in Firefox (not sure Chrome existed then). I tried everything I could possibly think of to figure out why the routes wouldn’t show up. The API calls were being made; they were completing successfully; distances were being measured correctly. What was going on? Finally, probably the next day, I took a look through the API docs hoping there would be an answer there. About 25 seconds into reading, there it was:
To display polygons in Internet Explorer add the “webgl” namespace to your <html> tag1
So, I had wasted a day of effort trying to debug what felt like a total edge case of a bug, when all that I really needed to do was read the documentation and follow the instructions that were plain as day. Want to draw polygons in IE? You have to tell it to do so. Dammit.
I wish I could say that it was at that moment that I decided to always read the documentation. But the reality is that I have (almost) always read the documentation. I read through the React docs before deciding whether or not to use it. Years ago, before writing a single line of code with it, I read an entire book on Spring2. And just last week, I spent the better part of a day reading through the docs for Stripe, all of it, even though I was only going to be storing and charging credit cards.
Why do I do it?
Two reasons: for instructions, reading through ahead of time gives me an idea of what I need to do. It let’s me take stock of whether I have the tools, the space, the time, that I need to get the task done. I get an overview of what I will be doing, and then when I actually do it, I can see how the steps (and pieces) fit together. I actually get a better sense of how it all works, because I know where I am going along the way.
But more importantly for building software, reading through documentation lets me see the tool (library, service, etc.) I am about to use in a larger context. If the docs are written well, then I learn about the concepts that are involved, which I could not glean as easily just from reading the code. When I read “Spring in Action,” I learned about dependency injection and inversion of control, why using unchecked exceptions could be better for webapps, and how to write more effective tests. Yes, I learned how to write better tests reading a book on Spring. That is damn good documentation.
Writing code may be little more than typing lines of instructions for a computer to interpret (and then arguing with your friends about whether or not those lines should end with semi-colons), but building software is a process of threading ideas together into a coherent and complex system. Understanding the concepts that the documentation presents is the key to figuring out how to put all of the pieces together.
And finally, reading the documentation is a way to fuel my inference engine (a.k.a. my brain). Our subconscious can only work with the facts that are in our brains to make creative connections. Filling up my brain with as many concepts as possible is the best way for me to come up with creative solutions to problems. If I had not read the sections about subscriptions in Stripe’s documentation, then I would never have thought that we could use it to implement a monthly billing system that is not technically a subscription.
As engineers, we hear “use the right tool for the job.” For learning a new library, the right tool is the documentation. Yes, you can learn what a library does by reading the code, but you cannot learn everything about what that code represents. That information is in the documentation.
-
This is not what the actual documentation says, and since it was 8 years ago, I cannot find the documentation, but you get the point. ↩
-
The first edition of “Spring in Action” was one of the best software books I’ve read; it was filled with very good explanations and examples, and it built up from core concepts to detailed implementations. ↩