Hey everyone and welcome to Developer Tea my name is Jonathan Cutrell and today we're going to be talking about reading the manual. If you've ever posted an issue into an IRC chat room for a programming language or an open source project or maybe you posted a question as a GitHub issue and you didn't read the documentation beforehand or perhaps the question that you're asking is very clearly answered in the documentation. A lot of programmers that you will encounter on that project will likely tell you to go and read the manual. Instead of answering your question, it's very likely that they will point you towards the manual which has already answered your question. But why is it so important that we read the manual? Why is it so important that we look over the documentation rather than just looking at examples of how other people are using a particular thing? The truth is a lot of the time the way that we learn and the way that we work is by looking at the way that somebody else has done something and emulating it, taking what somebody else has done that we think is working properly and adopting those practices for ourselves. I'm going to take a quick sponsor break and then I'm going to come back and talk to you guys about some of the problems you might encounter if you only approach things by emulating the way that other people are doing them and you skip reading the manual. Today's episode of Developer Tea is sponsored by DigitalOcean. DigitalOcean is simple cloud hosting built for developers. They're dedicated to offering the most intuitive and easy way to spin up a cloud server. And in just 55 seconds, you can deploy a solid state drive cloud server. And start at only $5 per month for 512 megabytes of RAM, a 20 gigabyte solid state drive, one CPU and a full terabyte of transfer. In addition to offering simple and affordable SSD cloud hosting, DigitalOcean is dedicated to building out a strong community and supports open source software. They offer a vast collection of hosting tutorials and invite Developer To submit articles and they pay $50 per published piece. Play your SSD cloud server with DigitalOcean today by going to digitalocean.com. Now DigitalOcean has been kind enough to provide Developer Tealisteners a discount of $10 when you use the code Developer Tea. So go to digitalocean.com and use the code Developer Teato get $10 off today and you'll get up and running with your own SSD cloud server in just 55 seconds. That's digitalocean.com. We're talking about reading the manual in today's episode. Now I mentioned before the break that the way a lot of us adopt tools and the way a lot of us learn how to use a given language or framework is by looking at the ways that other people are using them and then adapting them to our own problems, adapting what other people are doing to what we are doing. Now when we adopt tools and languages this way, it allows us to skip the deep dive. It allows us to skip the more in-depth studying of whatever that tool or language is and we don't have to spend so much time understanding the fundamental building blocks of that tool. We can go ahead and start using it right away. There's a few problems with this approach though. The first problem is that we can't see into the future so we may not know what problems we will encounter for making something incorrectly early on. At first it may feel totally fine, for example, to write an unlimited number of nested callbacks in your JavaScript code because it's readable to you at first. It seems perfectly readable and perfectly manageable but as you go down that road of writing nested callback after nested callback, it becomes much more difficult to manage. Another issue of not reading the manual is that you may not be accessing all of the powerful features of the things that you are using if you don't have the knowledge that they even exist. I'm sure every single person who's listening to this podcast episode has had the surreal experience of realizing that your TV or your computer or your phone has some hidden feature that you didn't even know existed because it wasn't on the forefront of that device and you found it later because somebody posted a blog post about it or maybe you stumbled on it accidentally and you wished, man, I really wish I had known about that earlier. We can do the same thing in our programming practices. In the previous example where you're writing nested callback after nested callback, if you had known earlier that promises exist and that there are better control structures for dealing with asynchronous functions in JavaScript, then you would probably have never even thought to write those nested functions. You could very easily handle those situations in much more readable ways with those built-in capabilities of JavaScript. I guess I should clarify that promises aren't in JavaScript yet, but they will be in ES6 once that has been shipped to all the different browsers. The idea here is that there are powerful features that we may not even realize exists unless we read the manual, unless we understand the construction of the language and the intention of the language or tool or software package. The same is true for things like APIs. We need to read the manual on how these APIs are constructed. The third reason and perhaps the most important reason is that we may make assumptions about how something works and those assumptions could hurt us in the future. We could be very wrong about how something works in a given language or project. This actually recently happened to me. I've been a musician for quite a while and so I own a good amount of musical gear. This includes a ton of cables and a ton of different input output devices. For example, the microphone and the preamp and the audio interface that I record through for this podcast, I've owned those since before I started this podcast. I've never taken the time to read about the different signal types and the different cable types. I've just judged all of those different pieces based on their appearance to me. I've also never read how to properly set up the preamp with an audio interface. I was trying out some new equipment with my original setup and it started to hiss. It started to make a really bad sound. I started looking up what we caused this hiss. As it turns out, I had things totally wrong. There are different types of cables that look exactly the same and I had never actually gone through the process of researching this or understanding different signal types. This is a perfect example of me assuming that what I knew about this subject was adequate and accurate. But if I had read the manual first, if I had learned about signal types and cable types before I started using them, then I never would have set up my preamp and my audio interface incorrectly. Now, you might be thinking to yourself, well, your audio sounds fine to me. I don't hear the problem. The truth is, I didn't hear the problem either. In fact, I still don't hear the problem with my current setup. When I introduced new equipment into my setup, that's when the problems showed up. Why am I telling you a story about my audio equipment? The same could be true for you in your situation. You could have assumptions about the different tools, the different languages that you're using that you don't even know are wrong yet until you introduce something new and you experience a problem at that point. Understanding the fundamental ways in which a given tool is constructed, although it seems very difficult and it seems non-productive, reading the manual early, understanding those building blocks early gives you a much better perspective when problems do occur. Then we'll use another good JavaScript example. If you approached JavaScript from the perspective of every other programming language, if you didn't know that JavaScript had asynchronousity built into it, then you would be very confused about what a callback function even does. You might be confused about why things are executing in the order that they're executing, learning and learning about asynchronousity even before you ever have any reason to try to use it will help you understand when and where you do need to use it when the time comes. We should read the manual, but to what granularity, to what level do I need to understand a programming language or a library? The best answer for that question is it depends, but I'm going to give you a few rules of thumb for how deep you should dive, especially in the early stages of using something. For programming languages, you should know all of the basic types that the language implements. By type, I mean integer or float or string and perhaps different types of strings and different types of integers if your particular language implements those and the differences between those types. Secondly, you should understand what kind of programming language you're using. For example, if you're using Ruby or Java, then you're using a classical object-oriented programming language. If you're using JavaScript, it is a prototype-based language, and if you're using Haskell or Closure, it's a functional language. Of course, that requires that you have a little bit of an understanding of what each of those things means and typically what happens in each of those types of languages. I never said it would be easy, but it's important that you understand these things. If you want to be a great programmer, you have to understand the fundamental ways in which the language you're using is constructed and intended to be used. If you're using some kind of software package or API, you should have a familiarity with the different modules that that API or software package implements. In this context, when I say module, I mean collection of functions that has to do with a given subject. For example, you should know if you are using jQuery, that jQuery has a CSS module, and jQuery can modify the CSS with a number of different functions. This also provides you with enough familiarity of the documentation that when you come across a problem, you know where in the manual to look first in order to try to solve your problem most directly. The same concept of understanding the modules that a given API or service or software package provides also applies to some programming languages. For example, the core libraries for Ruby, you need to understand what an enumerable does. Now lastly, you need to understand the input and output methods of a given programming language. For example, how do I access a particular value in a tuple in Python, and how do I get a value out of an object in Ruby or Java? How do I go about calling a function? And when this program begins to execute, where does it start? Where does the program entry point start? And the program is complete, where has it ended, and does it put something out to standard out that I can view in a normal context, for example, in a terminal window. How can I monitor my application? How can I interact with it? How can I see what's going on? Is there a log file? These are all the questions of input and output for a given language or a program. Now here's the thing. All of these things are covered in good documentation for just about any project worth that's solved. All of these questions will be answered in the documentation in the manual. So read the manual, take some time, and read the manual for each and every language or tool that you use. And this is especially important if you are relying on this particular tool or language for the primary parts of your job or the primary parts of a given project. If you're using something heavily, of course, you are more likely to experience those problems down the road if you don't have a fundamental understanding of the construction of the tools that you're using. Now, I want to make one final comment. Reading the manual does not mean that you have to memorize the manual. To be able to use these different languages and tools, you have references that are available to you at any given point in time. There's no reason to memorize it or to internalize it. There is a reason why computer science is so effective at abstracting things away. And that's because we have interfaces to the lower level details and we don't have to worry about them anymore. But that doesn't mean that we shouldn't understand them. And we'll be talking more about abstraction in the future and how much we truly need to understand about those abstracted pieces in order to use them effectively day-to-day. Thanks so much for listening to today's episode of Developer Tea. I hope it encourages you to start coding a little bit earlier because we have all of these resources that are available to us. Speaking of resources, check out Digital Ocean today's sponsor. They provide a very fast and easy way to get up and running with a Cloud SSD, just 55 seconds. And if you use the code Developer Tea, today you can get $10 off. So go check that out. All the links will be in the show notes. Thank you again for listening to today's episode and until next time, enjoy your tea.