Have you ever been on the verge of tearing your hair out trying to figure out why a line of code you’re working on is failing? You’ve re-read the code. You’ve checked your quotation marks, semicolons, and variable names. You’ve made sure you’re not missing a bracket. Nothing has helped. It’s time to turn to documentation (insert audible sigh here).
Technical documentation is not always easy to navigate, especially for a new coder. Little of the documentation you find online is written by one person so you can’t get a sense of one person’s writing style and adjust accordingly. Documentation contains jargon newbies may not know yet. Terms used in one language may be used a little differently in another. And, don’t even get me started on the differences in the details of each language like which bracket is used. Given these challenges, I wanted to provide a few tips on reading documentation.
Be patient. As the saying goes, Rome wasn’t built in a day. Just like any other learning process, learning by reading documentation takes time. If you start to feel frustrated, take a break, move your body a bit, and then come back to it with fresh eyes and a clearer head.
Review terms. When reading documentation, you’ll come across terms like method, instance, and object that may have different connotations outside the world of coding. Review key terms frequently when first starting out so you’ll be clear on what they mean when you run across them in documentation.
Develop a reference library. Online documentation is where we go first these days to get information quickly, but online sources may not be completely accurate, in part due to the speed with which they can be produced. Printed books may become outdated as changes in technology occur, but they can continue to serve as reliable reference materials for the basics. When reading documentation online, printed reference books can help clarify concepts.
Use multiple sources. Technical documentation is not always written with the newbie in mind. Therefore, there may be gaps because the writer assumed the readers already knows a key point. Unfortunately, new coders don’t know what they don’t know. Reading about the same topic on multiple sites may fill in knowledge gaps that seasoned coders may not have. Reading documentation on multiple sites also helps you discover which resources communicate in a way that works for you.
Read the overview. Lots of times we want to jump straight to the issue we’re trying to resolve. Reading the overview, if there is one, provides a framework for what the code should be doing. Reading documentation without checking the overview can leave you without information that can help you better understand what’s going on underneath the hood.
Check the version. Code changes. That’s a fact. Version control and version numbers help guide you while reading documentation. Check the change notes and version information to figure out when and how issues with the code were addressed.
Learn to read the code. Reading documentation may not be enough when you’re trying to understand what’s going on with a program. Examining the source code can make all the difference in the world. Take advantage of all the code examples, not just by copying them, but by reading and analyzing what the code is doing. Test the code yourself to see it in action. Change things and run it again. Break it. Then figure out how to fix it.
Clean up the code. One of the first things I learned at TTS was to keep my code clean and organized. All that indenting and lining up of the brackets really does help with reading the code and, by extension, understanding what’s going on when you’re reading documentation. Developing good coding habits on the front end helps when you need to find a solution to a problem.
In the end, the best way to learn is by being patient with yourself, reading documentation, and writing lots and lots of code.