Reading Documentation Upfront

Before I was actually getting paid to write code, I got extremely accustomed to picking up new frameworks and libraries very quickly. I'd bootstrap a new web application in Rails in one week, but then the next week I'd be using Python and Flask for a different project. I also "learnt as I went", and got used to Googling for things as I needed them.

My relationship with documentation was complicated — I'd always read the "Getting Started" pages and then mostly forget about the documentation, and would only come back to it if Google or someone else linked me to it. Sometimes, this led to some extremely lazy questions on StackOverflow.

When I started my professional software engineering career, these habits didn't really go away. I'd join a new team or project and then just start contributing with code as quickly as possible, mostly by doing pattern matching on existing code and by asking for help/Googling as needed. This worked out okay for a while but then I started noticing that the more senior engineers were able to diagnose bugs related to our dependencies much harder than the ones I took on, and they were also able to discuss internals of the libraries and frameworks we used to build our software. I also remember my manager saying things like "I read that library's documentation, I don't think it'll work very well if we try to do X with it".

This made me realize that I should actually be treating documentation more like a book, by reading it end-to-end before I npm install'ed something, especially for dependencies that were going to be widely used within a project. Of course, this is easier said than done since it requires a great deal of discipline.

What about reading the code?

I fundamentally believe in treating our dependencies' code as our own code (it's part of our binaries, just like the code we write ourselves), and reading some of that code before we bring it in, similarly to how we do code review for what our coworkers write.

However, there's a lot to be said this. I'm not going to recommend that people go out and read the source code for React.js if they want to use it. Yet, for smaller libraries, this can make a lot of sense. There's also some techniques for more efficiently reading the code of an open source library, and I may write another article about this in the future.

Do you need to read the whole documentation?

As with many things like this, it depends, but probably not. As I mentioned in the beginning of the article, it's certainly possible to use a library or even a programming language without reading its full documentation. There can be diminishing returns on the time that we invest in reading documentation, especially when you're reading things like API references, which are usually consulted and not read upfront.

There's exceptions to every rule, but I find myself asking the following questions when trying to decide how much I should be reading.

• How long are we going to use this project for?
• Is it a small UI component or a framework that will define the architecture of our application? (This is a very large spectrum, so take this question with a grain of salt)
• Is this so small that I should also be reading the code?
• Is this API reference something I should skim or read fully?
• How complex are the internals? Do I need to understand how this thing works or do I just need to be able to use it?

Finally, it's important to note that not all documentation is structured equally. Some projects may have a "Handbook" which is a great first read for newcomers (e.g., https://www.typescriptlang.org/docs/handbook/intro.html). For people that strongly prefer learning by doing, a "Tutorial" section can teach you most of the basics (e.g., https://reactjs.org/tutorial/tutorial.html).

When in doubt, I tend to lean on the side of reading more than less, since an extra hour of studying can easily pay off in the long run, and it's rarely a wasted hour.

Working out the discipline

There's various ways of dealing with the discipline required to read documentation upfront. For example, if you find it hard to stay focused while reading something long, you definitely need to break it up and use "markers" to know where you last left off. Here's some other techniques that have worked well for me.

1. Required Reading Lists

For new hires that join your team, make sure they have a "Required Reading" list that they are expected to complete within the first 2-3 months. Make sure to let them know exactly which pages/sections they are expected to read, along with any other notes which you may find relevant. Here's a very short example:

If you're joining a new team and they don't have a "required reading" guide, ask people on the team what you should read and then create one! Attach it to your onboarding guide and nudge folks to give it some love every now and then.

2. Taking notes and sharing them with the team

Recently, we started using React Testing Library at work to write frontend integration tests. It's likely that we'll continue to use this library for years and years to come, and before we decided to use it, I made my fair share of prototyping and reading about it. However, just as we started using it, I decided to read its full documentation, end-to-end, like a book.

I also decided to take some very raw notes about what I read and to share them with the team. This was also helpful as a way to "mark" where I last left off since I wasn't able to read it in one go. However, this was primarily helpful as a motivator for me to work out the discipline to read everything. Finally, once I was done I was able to share with the team which pages they should also read and which ones they can skip which saves everyone time.

3. Reading groups are fun!

Soon, at work, we're going to be writing our new code using React Hooks (if you've never used React before, it's a new API for implementing UI components with React). There's a lot one should read about React Hooks before starting to use them, since they can be very different from React Class Components.

Definitely on this list is the official documentation, but there's some other articles and reading guides that we've found helpful. To help us all get through this before the switchover, we created a reading group which basically consists of an internal spreadsheet with the list of articles and what each person has read so far. We will then build on top of this by scheduling some calls to discuss specific things that we're finding difficult, and we can also asynchronously discuss other things over Slack and email.

Conclusion

Valuing the importance of reading documentation upfront was certainly a hard learned lesson for me, something I struggled with time and time again. Working out the courage to read the full documentation of a new library or framework that we're adopting can be hard, but I find it's more rewarding than we usually think.

I've been applying this approach more and more as I get more experienced, and don't see myself switching back. The next step for me is trying to convey why I think this is important, hence I wrote this article, but I think that sharing the notes I take about the documentation I read internally more often will also persuade others into trying this out.

Reach out on Twitter if you have something to add!