Hey everyone and welcome to Developer Tea. My name is Jonathan Cottrell 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, say for example, 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? 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. Plans start at $5. $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 developers to submit articles, and they pay $50 per published piece. Deploy your SSD cloud server with DigitalOcean today. By going to DigitalOcean.com. Now, DigitalOcean has been kind enough to provide Developer Tea listeners a discount of $10 when you use the code DeveloperTea. So go to DigitalOcean.com and use the code DeveloperTea to 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. 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. So 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 to do that. If you don't have the knowledge to do that. 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 this. We can do the same thing in our programming practices. So 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. At least you may have taken these Camp Camp even realize exist unless we read the manual, unless we understand the construction of the language and the intention of the language or tool or software package. And 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 input. The preamp and the audio interface that I record through for this podcast, I've owned those since before I started this podcast. Now, 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, I started to hiss. It started to make a really bad sound. I started looking up what would cause this hiss. As it turns out, I had things totally wrong. There are different types of cables that look exactly the same. 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. manual first. If I 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. And the truth is I didn't hear the problem either. In fact, I still don't hear the problem with my current setup. But when I introduced new equipment into my setup, that's when the problem showed up. Now why am I telling you a story about my audio equipment? Well, 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. And 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 asynchronicity built into it, then you would be very confused about what a callback function even does. You might be confused about what a callback function even does. You might be confused about why things are executing in the order that they're executing. Reading and learning about asynchronicity 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. So we should read the manual, but to what granularity, to what level do I need to understand a programming language or a library? And the best answer for that question is it depends, but I'm going to give you a few examples of how you can use it. So let's start with the basic 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 Clojure, 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. Now, I never said it would be easy to understand the language of a language, but I'm going to give you a few examples of how you can use the language of a language. First, you need to understand the fundamental ways in which the language you are 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. Now, in this context, when I say module, I mean collection of functions that has to do with a particular type of language. So, if you're using a specific type of language, you should know that the module is going to be used in a specific way. For example, if you're using JQuery, you should know 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. This same concept of understanding the modules of a language is a very important part of the process. If you're using a given API or service or software package, it 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? When 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 of 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 its salt. 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 to memorize the manual. 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 abstraction. 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 DigitalOcean, 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.