How to Read Documentation Without Defenestrating Your Computer
A Beginner’s Guide
Back away from the window. That laptop cost a lot of money, and more importantly, if you hurl your MacBook from your sixth story walkup, python.org/doc/ will win. Plus you might hit your neighbor Geraldine, who will definitely sue, and you’ll lose your job, your family, your friends and end up in prison for years, and when you finally get out you’ll wish you had a laptop to look for a job, but you won’t have a laptop because you threw it out the window, which is what got you into this mess in the first place. And all you wanted to do was look up how to make a regular expression…
Documentation can be a nightmare — especially for the beginner. This article will provide some tips on how to approach these finicky guides. It will be geared mostly towards the new, bright-eyed, bushy-tailed programmer, but these tips and tricks can be useful at any stage of your coding journey. This article is for you if:
- You groan at the thought of learning a new technology because you know it will involve looking at docs.
- Someone tells you “You’d better get comfortable with reading documentation!!” and your brain responds “But how… do I do… that?”
- You wonder why docs were created in the first place if they’re so darn hard to use!
So how do you go about reading documentation effectively? The good news is, the first tip might make your life really easy.
Tip #1: Don’t.
Yeah that’s right. Don’t read it! Okay there’s a bit more to it than that, but it’s important to remember that not all coding problems are best solved by reading documentation. Unfortunately most are. But there are instances when frantically searching through page after page of verbose, dense language will waste your time, your patience and your energy. Here are some situations where your problem would be better solved elsewhere:
- When you have a weird error message. Copy & paste that baby right into a search engine. You’ll find a variety of resources pop up, but your best bet is probably the one that links to Stack Overflow.
- When you’ve done this before. If you know you’ve done something similar (or identical) in another project, go check that out first. Seeing how you implemented this feature in another file can help jog your memory.
- When you don’t know what you’re looking for. This would also benefit from a google search. It may lead you to documentation, but it may also lead you to a handy Medium article (ahem) or a Youtube tutorial that explains the solution in simpler terms.
And then of course, there will be moments where you have no choice but to dive in. To that I say:
Tip #2: Start at the Beginning.
This seems obvious, but out in the wild, it’s rarely done. Documentation can be daunting, and sometimes it’s difficult to know where to begin. Most technologies have guides for how to get started and for how to read the docs themselves (yes, docs for the docs—it never ends.) Take advantage of these. If you find yourself staring at a page and everything looks like hieroglyphics, you probably don’t understand how to read these docs yet, and the best way to learn is from the guides that say “Start Here!” or “Quick Start.” Once you’re ready to move to more advanced material, take some time to familiarize yourself with how everything is set up before you dive in. Every technology has a different way of organizing their documentation. It’ll save you time (and sanity) later.
Tip #3: Slow down bucko!
This one is hard for programmers to embrace. We get excited about building an API, or solving a problem, or implementing a new feature, and in our rush to make it work (god, please just work!), we forget to slow down and enjoy the ride. If you’re skimming the documentation to get straight to the solution, you’re likely skipping a bunch of information that helps solve your problem. At Fullstack Academy, we’re taught that “debugging is the process of fixing a broken understanding, not broken code.” Your bug is likely the result of a fundamental misunderstanding about how something works. Take your walk down Docs Avenue at a leisurely pace, stopping to smell the definitions, examples and confusing jargon, and you’ll leave with the answer to your problem and a better foundation for how this technology works.
Tip #4: Find the Visuals.
There’s nothing worse than trying to parse verbose, complicated language when you’re already frustrated and looking for an easy answer (there isn’t one). If the docs have visuals, use those in tandem with their explanations. It’s easier to understand a concept when you can reference a visual representation. For example: Git has documentation that looks a bit like a cat with chalk for paws danced on a blackboard:
But Git also has a lovely online book (it’s free!) that offers in-depth guides to common features, with loads of pictures and detailed examples.
Look for anything tangible you can find, whether they’re code snippets, diagrams, flow-charts, etc. They are invaluable tools for making the abstract and the theoretical concrete. Famously, a picture tells a thousand words.
Tip #5: Bookmark the Tricky Bits.
When you find something you’ve spent half an hour looking for, celebrate by adding a new bookmark. Why? Because you’ll be back. And not the quick way. A good rule of thumb is if it took you more than a quick google search to find what you were looking for, it’s time to add it to your bookmarks folder. Make it a habit. Find some joy in having the most gorgeously managed bookmarks, organized in folders that are semantically named. Future you will thank you.
And as a sendoff, a quick reminder of the #1 rule in coding: if you’re feeling stuck or frustrated, take a break. When you pry yourself from your laptop, your brain gets a chance to make new connections and associations that you don’t have access to when you’re deeply focused. Taking a moment to go for a walk or do the dishes can sometimes feel like giving up. You may lose the battle, but you’ll win the war. And you cannot let python.org/doc/ win.
