On Reading Docs
As a developer, documentation is both your greatest ally and your worst nemesis. It's the key to unlocking the power of libraries, frameworks, APIs, and even entire programming languages. Yet, many developers struggle to effectively navigate and extract the information they need from documentation. It's a skill that can be learned, and it's one that can make a huge difference in your productivity and the quality of your work. New developers often lack this critical skill, and find themselves stopped in their progress towards becoming a better dev because of it.
I'm currently writing the docs for Vewrite, a project management tool for writing teams. It occurs to me that I've been writing documentation for a long time, and I've gotten pretty good at it. I've also gotten pretty good at reading documentation, and I think that this is a skill that is often overlooked.
Let's talk about how to equip you with the skills to read documentation better, turning this often daunting task into a smooth and efficient process.
Why is reading documentation challenging?
I've talked, at length, about how I think that Docs Deserve More Respect and how you can Quantify Your Documentation's Success.
Good documentation is essential. It provides the definitive guide to how software works, saving you countless hours of pointless, frustrating trial and error. Bad documentation is a nightmare. It's like trying to navigate a maze blindfolded, with no map and no sense of direction, guided by a liar.
If you have access to the code you are working against, that's great and you should use it. Poke around and see what you're supposed to do by reading the code. But, in many cases (and almost all of the time with proprietary software), you're going to have to rely on the documentation to get you through. However, documentation can vary wildly in quality. Some is meticulously crafted, while others can be uninformative, outdated, or even misleading. This inconsistency is one of the reasons why reading documentation can be challenging.
No clear structure
Some docs are just a dumping ground for information, with no clear structure or organization. This can make it difficult to find what you're looking for, and you end up spending more time searching than actually learning. A well-structured set of documentation will have a clear table of contents, with sections and subsections that guide you through the material in a logical order. This makes it easier to navigate and find the information you need.In general, I'll also recommend some Getting Started section which points different types of users to the information which is most critical to them.
Too much information
Information overload is another common hurdle. Docs can cover a vast range of features and functionalities, making it difficult to find the specific information you need. For example, a large framework might have hundreds of classes and methods, and trying to find the one you need can feel like searching for a needle in a haystack.
Unclear technical jargon
Unclear technical jargon can also be a barrier, as documentation is inherently technical, and sometimes the terminology can be confusing, especially for newcomers. This often stems from the assumption that the reader has a certain level of prior knowledge as it is largely written by the team who has developed the software and has an intimate knowledge of its innner workings.
Outdated information
Outdated information can be a major problem. Software evolves rapidly, and documentation can sometimes lag behind, leading to frustration and wasted time. A library might have deprecated a certain function, but the documentation might still describe it as the primary way to perform a task. The teams who produce software should be including accurate documentation creation and upkeep in their backlog as part of their process. Unfortunately, in the haste to get features shipped to market, corners are often cut. I've spent the better part of the last decade advocating for better processes that lead to better docs at a number of companies, and the biggest challenge here has been explaining to stakeholders where the value is.
How to read documentation effectively
Over the years, I've developed a structured approach to how I tackle reading new documentation. I've found that this approach helps me quickly get up to speed with new tools and technologies, and I hope it can help you too.
By and large this method has three parts: understanding the structure of the documentation itself, understanding the way that the system I'm learning works, and lastly engaging with the material in the docs. First I get the lay of the land, and then I try to focus in on the details.
Understand the structure of the documentation
Docs are written by people, and every sysyem is going to be different. That means that every set of docs is going to be different. Some docs are organized by feature, others by use case, and still others by API endpoint. Understanding the structure of the documentation is key to finding the information you need quickly. Start by scanning the table of contents to get an overview of the topics covered. This will help you get a sense of the scope of the documentation and where to find specific information. You'll want to quickly click through the docs and get a sense of how things work, how they are organized, and where you can find reference materials if there are any.
I find that this initial run through also trickles some information about the system and its components into my brain. It's not comprehensive at all, but it's a good start.
Understand the system
Every piece of software is a system, and understanding how that system works is key to understanding how to use it. This is where the documentation can be a huge help. Good documentation will provide you with a high-level overview of the system, explaining how the different components fit together and how they interact. This can help you understand the context in which a particular feature or function is used, and how it relates to the rest of the system. This is where you start to get a sense of how the system is supposed to work, and how you can use it to solve your problems.
A lot of the problems that you'll encounter when building software will be because you fundamentally don't understand how what you're building with actually works. This is where the documentation can be a huge help. It can provide you with the context you need to understand how the system is supposed to work, and how you can use it to solve your problems. Use that to your advantage and you'll be able to build better software, faster.
Engage with the material
This is often the most tedious and boring part. You have to actually take a few hours and read through the entire docs. For smaller libraries or APIs, this isn't going to be a big deal and you'll be able to fit most of it into your head. For larger systems, this is going to be a multi-day process. You'll want to take notes, ask questions, and engage with the material in a way that helps you understand it. This is where you start to get a sense of how the system is supposed to work, and how you can use it to solve your problems. If it doesn't all fit into your head now, that's ok. You'll remember more than you think you will, and when you're actually doing development it will be an order of magnitude faster to find an answer if you've already seen it once.
Use AIs to help you
I've actually found that modern AIs are absolutely awesome for this step. You can use them as you would a more experienced developer and ask them questions about the system, the functionality, and the docs themselves. You can't trust everything that they say, but you can't really trust what another developer always tells you. I've found that being able to have a discussion with an AI about a library or API really helps me understand how stuff works at a deeper level.
Strategies for effectively reading docs
Despite these challenges, mastering the art of reading documentation is doable. Here are some strategies to keep in mind while you are digging around in docs, looking for an answer.
Set a clear objective
If you don't know where you're going, you may never get there. Before you dive into a set of docs, you may want to set a clear objective for yourself. Are you trying to understand a specific function, integrate a new library, or troubleshoot an error? Having a clear objective will help you focus your search.
For example, if you're trying to fix a bug where a specific function isn't returning the expected value, and your code matches what the docs say that you're supposed to do, your goal is to understand the function's place in the wider system. The problem is going to be a few levels up and the docs are likely going to be the key to understanding how the software works at a higher level.
Don't immediately jump into the nitty-gritty details. Begin with the introductory sections, tutorials, or quick start guides to get a high-level understanding of the system. Your assumptions will often be wrong, and it is good to base your work on a foundation of truth. Think of it like reading the abstract of a research paper before diving into the full text. These introductory materials often provide a roadmap to the rest of the documentation.
Use the structure of the docs to your advantage
Use the table of contents and search function (these are your best friends) to quickly locate the sections you need. Don't be afraid to experiment with different search terms. Scan through the entire table of contents. Poke around and get a really good feel for how the documentation is structured. Sometimes you will find that your answers are hidden adjacent to where you thought that they would be.
Leverage code examples
Real-world examples are invaluable, and the best docs are going to include them. They demonstrate how to use the code in practice and can often clarify confusing concepts. Pay close attention to the context in which the examples are used. A code snippet demonstrating how to use a particular function is much more helpful if it's accompanied by an explanation of what the function does and why it's being used in that specific scenario.
Pay attention to the details
When looking at function or method definitions, carefully examine the data types of the parameters and return values. This will help you understand how to use them correctly. Sometimes, crucial information is hidden in footnotes, warnings, or less prominent sections. Make sure you scan the entire page, not just the headlines. A seemingly minor note might contain a critical piece of information that can save you a lot of trouble. Documentation often contains links to related topics or other parts of the documentation. Don't hesitate to follow these links to gain a deeper understanding. These links can often lead you to more detailed explanations, examples, or even the source code itself.
Use the code if you can
This is one of the biggest reasons why I believe that open-source can be such a boon for companies who want to build an ecosystem of developers around their software. Sometimes, the best way to understand how something works is to look at the source code itself. Don't be afraid to dive in, especially if the documentation is unclear. Reading the source code can give you a much clearer picture of what's happening under the hood. Try out the code examples and modify them to see how they behave. This is a great way to solidify your understanding and discover edge cases. Experimenting with the code is like conducting your own little science experiment. You can change the inputs, observe the outputs, and gain a deeper understanding of how the code works. If you're still stuck, don't hesitate to reach out to the community for help. Forums, mailing lists, and online communities are valuable resources for getting your questions answered. The developer community is generally very helpful, and there are often people who have encountered the same problems you're facing.
Engage with the material
Reading documentation shouldn't be a passive activity. Engage with the material by taking notes, jotting down key points, examples, and any questions you have. Annotating the documentation (if possible), highlighting important sections and adding your own comments can also be helpful. Creating your own examples, writing small programs that use the features you're learning about, is a great way to reinforce your understanding. It's like practicing a musical instrument – the more you do it, the better you get.
You can do it
Reading documentation is a skill that improves with practice. By adopting these strategies and actively engaging with the material, you can transform documentation from a source of frustration into a powerful tool for learning and development. So, embrace the documentation, and unlock the full potential of the software you're working with!