Reading Documentation is fun?
definitely when you do it right.
I’ve become bored with programming tutorials. Avoiding tutorial hell is a big motivation for doing independent research, which is usually just Google searches.
A while ago, I found a video of a programmer explaining their process for learning new programming languages. Contrary to my expectations, instead of looking up a tutorial video for beginners, he simply found the relevant documentation for that language, read through it and started testing things out, basically figuring out what worked and why. It was an eye-opening experience for me, since I didn’t usually approach learning new things that way. I’m not saying I haven’t come across any documentation, but my past, limited experience with docs have been daunting, and the contents seemed cryptic. Recently I’ve developed the patience to not only read but actually test and build stuff.
Something I’ve realized is that when it comes to learning new things, and in this case a programming language, is that the approach matters more than I thought. Tutorials aren’t inherently bad, the issue is that the general expectation of what watching one can do for you is overblown. Tutorials are a more flexible human entry point to new things. I never retained much from watching tutorials, but as an introduction to unfamiliar territory, good tutorials were very useful. Now with documentations, there’s less flexibility as they demand rigor. They show you the proper way to do things.
Recently, I’ve found myself learning JavaScript. I’ve never been much of a front-end enthusiast, but now that I need that particular skill set for certain projects, here I am. My goal during this stint is to know just enough that I can build basic stuff and explore other supersets of JavaScript and its libraries. I also don’t know how feasible that is, as I haven’t done anything front-end related in a while. So this time, instead of going on YouTube and looking up a beginner JavaScript tutorial, I went with the documentation by MDN1 for the language which I’m working through. I’m doing this to get an overview of how the language works and how my thought process when building with JavaScript should look like.
I found out a couple of things about docs while I was trying to figure out what makes some useful and others, in my experience, terrible. When I come across good docs, they usually have a guide section or a getting started section and a reference section or library. I’ve learned not to skip the getting started section, as it gives an overview for what to expect from the subject. For example, MDN’s JavaScript web docs, which I’m using now, have this structure.
The documentation is well-structured, and the beginner tutorials help me understand the overview of JavaScript as a language and what to expect as I learn. On the other hand, the reference section is more like a glossary or a dictionary and isn’t meant to be read through. It is a waste of time to read through them as references, prioritize information density, as I quickly realized.
I believe exploring documentation is how you build depth. Although we’re usually encouraged to learn just enough to build, I sometimes like to lift the hood just to examine things. This often leads to me biting off more than I can chew, but at least I take a bite. The most important thing I learnt from going through coding documentation is independence and active learning, which I see trending downward. Back then, I was too comfortable ignoring what I didn’t know and had a general lack of curiosity, which was worrying, but reading documentation encouraged me to explore and decipher information, especially information I’m ignorant about.
Not all docs are equal. I love when I can see the big picture when it comes to the subject, and sometimes I come across docs that explain the pieces so well, but there is no clear roadmap2. So what happens when you encounter some garbage in the wild? You’ll have to switch up your approach. Even though it may seem like a step backwards, the way I approach difficult docs is to write the code before reading the explanations or description. This is because I see what each line of code does, and that is more useful than just reading rigorous definitions.
Over time, I’ve noticed what good docs usually have;
The docs are up-to-date, as you’ll be surprised at how often this becomes a problem for me, seeing as old versions of a doc are sometimes more popular on Google
They have a guide section, reference docs and API descriptions. These are the minimum for making my life easy as a developer
They were structured to allow skimming. If I couldn’t skim, the experience was going to feel like a slog if anything
Good docs didn’t lack examples. Having lots of examples to work with, and most importantly code to break so I could get familiar with all the types of errors and why they happen, was really important. I know AI is nice for fixing up some stuff, but I don’t want this to become a plug and play experience, or else I’ll rather spend my time doing something else.
Now, after effectively exploring the documentation, the next step is to make a lot of projects. In the past, whenever I reached the point where I felt like I should build more instead of learning, but had no ideas, I just copied. It didn’t matter that it had already been built, the most important part was that I hadn't built it. Clones all the way. That’s the same thing that’s going to happen once I stop procrastinating and get through the JavaScript docs.
The Mozilla Developer JavaScript web documentation
I would recommend reading - How to Read Programmer Documentation by zed