Hey everyone and welcome to Developer Tea. My name is Jonathan Cutrell and today we're going to be talking about when documentation can be a bad thing. That may sound surprising to you. Documentation is a good thing, isn't it? We always rely on documentation, especially when we are learning how to use a new tool or when we run into a bug. We very often are told to go back and read the manual, go back to the documentation, go back to the instructions basically for a given tool or a language. But there are times when documentation can be a bad thing and that's exactly what we're going to be talking about today. First, I'd like to thank today's sponsor, hire.com. If you are a designer or a developer and you are looking for a job, hire.com may be the perfect place for you to start that journey. We will talk more about what hired has to offer to you later on in the episode. By the way, if you aren't looking for a job, hired has something to offer you as well. We'll talk more about hired later on in today's episode. But first, I want to jump straight into this discussion about documentation. For the sake of discussion, I want to define what documentation is. Documentation is a description of how to use a particular thing. It's instructions of how to use a particular thing. In code, documentation is talking about how to use a library or a language. Documentation is not a description of how the thing is built, but rather how I should go about interacting with that thing. The public API, the public methods, the configuration options, all of these are the things that go into the documentation. Most of the time you'll see examples in the documentation. You'll see snippets of code that explain how to use a particular feature, and that's what documentation is for. It seems like that would be a good thing in just about any scenario. That is true. In just about any scenario, documentation is of utmost importance. This is true for client projects. It's true for open source projects. It's true even for personal projects. But there are times when documentation can go bad. There are times when it can be even harmful. We're going to talk about two scenarios today where documentation can be harmful. By no means is this comprehensive. I would love to hear other times where documentation has actually bitten you as a developer. I want to talk about two scenarios today. The first one, we will talk about, and then we'll take a quick sponsor break, and then we'll talk about the second one. The first one is documentation of private methods or things that are in constant fluctuation. The practice of documenting private methods can be harmful because those private methods are most likely to change. When you're refactoring code, most often the internals of a public method, the API that anybody is able to look at and use, those internals can be rewritten without breaking the outward facing API. The documentation of the outward facing API can stay consistent and up to date much easier. You could go through multiple versions of a given product without ever actually even changing the user facing documentation because the API doesn't necessarily change. But if the internal code, the private method specifically, if there's change in your trying to keep up with them in documentation, it's likely that you are sinking more time than is practically valuable into documenting those methods. With methods that are in consistent fluctuation, changes to the documentation will be required far more often than is necessary. Instead of doing an in-depth documentation practice of your private methods, simply create a trail of readable commit messages or in-line commenting that explain what a given method does. Pair this with good tests that provide good coverage of all of your public methods and you have a consistent system without having to go through and painstakingly document things that are likely to change in the near future anyway. So that's the first scenario where documentation could be a negative thing, could be a harmful thing and that is when you're documenting private methods or things that are in constant fluctuation. Now, I want to take a minute to talk about today's sponsor, hired.com. If you are looking for a new job for the new year, hired could be a perfect place for you to start that journey. It is free for you to go on to hired and submit your application to over 2,000 companies that hired works with. They provide salaries from $75,000 all the way up to $250,000. If you get a job on hired, you get a bonus. We'll talk about that more in a second. And by the way, you never actually even have to talk to the company before you get an offer. Hired is not a gimmick. They have companies like Uber, GrubHub, Squarespace, GitHub, Facebook, Twitch, Opentable, Hip Monk. If you go to hired.com, you can go and look at that list of companies by the way by just visiting hired.com. But here's the extra incentive for you to visit hire.com today. If you go to hired.com slash Developer Tea, of course, that link will be in the show notes. If you visit hired.com slash Developer Tea and you create an account and you end up getting a job through hired after doing that, your $2,000 bonus that hired normally would give doubles to $4,000 just for being a Developer Tealistener. So go to hired.com slash Developer Tea today to start your journey towards your brand new job. Thank you so much to hire.com for sponsoring the show throughout 2015. So let's jump right back into our discussion about when documentation can be a bad thing. You know, we've already said that documentation of private methods or things that are in constant fluctuation, that's not very helpful, that actually can be a huge waste of time for the person who's documenting it. And most often, the documentation of public methods is much more useful than the documentation of private methods. The second scenario where documentation could be harmful is when your documentation goes out of date or is incorrect, is factually incorrect. This most often happens when the documentation is not maintained as fast as the actual features are being developed. Have you ever used a library or plugin that had conflicting documentation? It's the most frustrating thing to encounter. Perhaps you've used code examples from the documentation only to find out that they were either ineffective or worse, they introduced brand new errors into your application. This is the worst kind of documentation out of date or incorrect documentation. In fact, the developer would likely be better off reading the source code directly than reading incorrect or out of date documentation. This is true for a lot of reasons. But number one, when there is an endorsed source of truth about a particular project or language, documentation that is directly attached to it, the developer is very unlikely to not trust that documentation. After all, the person who wrote the code certainly shouldn't write incorrect directions on how to use that code. There must be something else wrong with my code. As a developer, if I encounter that problem, the Google Chase then ensues and the developer ends up confused. If they're lucky, they find a stack overflow post where somebody points out the fact that the documentation is indeed out of date or incorrect. It is very likely that the developer will opt out of using that language or that project in the future for fear of getting stuck again with a problem that they are unable to find the solution to without actually digging into the source code. Another very real concern about having out of date or incorrect documentation is that Google is quite good at identifying the most reputable source on a given subject. If you are the developer, the actual author of say an open source project, then your documentation will be connected very strongly to searches related to that project. If the documentation is poorly constructed, it shouldn't be what comes up at the top of the Google search results. At this point, you're going to have a very hard time finding the answers to your questions when the documentation is incorrect. This could kill an open source project very quickly. Those are the two scenarios that I want to point out in today's episode about when documentation can be a harmful, bad thing. A number one again was documentation of private methods or things that are in constant fluctuation. Things that are going to change very soon. It's likely that you shouldn't be documenting those, but instead you should be documenting the public APIs that should stay consistent throughout release cycles. In number two, documentation that goes out of date or is in some way incorrect. The moral of the story is, as you practice documentation, do so for the most important methods, the public API, the things that are going to be lasting and the ways that people are going to be using the primary chunks of that application, spend your time documenting those pieces of your project, your application, whatever it is that you're building. If you're going to invest in writing documentation, which you should, by the way, if you're going to invest in writing documentation, you have to keep it up to date and you have to be certain that every code example in that documentation works. You have to be certain that each and every piece of that documentation is representative of what is in the code and what will actually work. Your documentation has to be correct if you're going to publish it. If people are going to rely on that documentation to use your code. I hope this has been an interesting and enlightening episode about documentation. Thank you so much for listening and thank you to today's sponsor, hire.com. By the way, hired provides a bonus to people who refer others to their platform. Go to hire.com slash Developer Tea. If you have someone that you want to refer, you can get a third of, it's about a $1,300 bonus. So go and check it out hire.com slash Developer Tea. Thank you again for listening to today's episode. If you are enjoying Developer Tea, there's two things you should do. Number one, you should subscribe to the show and whatever podcasting app you use. This ensures that you don't miss out on any future episodes. Number two, go to iTunes and leave a review for Developer Tea. This helps other people just like you find Developer Tea. Thank you so much for listening and until next time, enjoy your tea.