The Power of Documentation - Transforming Your Development Practices

Welcome to Building Better Developers, the Developer Nord podcast, where we work on getting better step by step, professionally and personally. Let's get started. Well, hello and welcome back. We are continuing our season on the developer journey. We are here at Developer Nord, Building Better Developers, the developer journey to becoming a better developer. My name is Rob Broadhead. I'm one of the founders of Developer Nord. I'm also founder of RB Consulting, where we help wrangle technology. Basically take that sprawl, simplify it, automate it, integrate it, whatever we need to do to get you to that big nasty thing that you had. And now it's nice and sleek and helps you get your job done faster. We're like the iPod of technology, something along those lines. On the other side is Michael, and I'm going to go ahead and let you introduce yourself. Hello everyone. My name is Michael Milos. I am one of the co-founders of Developer Nord and founder of Envision QA, where we help small to mid-sized companies and clinicians and healthcare companies build software to meet their business needs, as well as help them identify if the current technology they're using is what really is beneficial for their business. This episode, everybody's favorite topic as a developer, documentation. We're going to talk about that because everybody complains that they get something that wasn't documented, but also nobody likes to document things. And so now we know why nothing is that. That's why we complain all the time is because we don't do it. Nobody else does it. So hey, this is how you become a better developer is you do the things that nobody else wants to do. A documentation is like testing to me a little bit is that it has always been left behind. There's always things like, eh, it'd be great if we have it. We know we should have it. We know we should do it. We a lot of times know how we should do it. We just don't. We run out of time. But also in the summer vein is that the tools to help us document have come a long, long, long, long way. So we really need to be more cognizant of that. At the very least, understand what your environment, language, whatever it is, what your tool provides in the way of documentation. For example, if you're writing APIs and you don't know what swagger is or those types of tools, then you need to like right now, just pause, Google it, look it up, you know, with your API, however you build it. And they probably got 18,000 tutorials on how to set it up. Also if you don't know how to use postman in your building APIs, pause, go learn how to use postman. And actually postman will help you do documentation. So that's a side note there. There are so many tools out there to help you straighten stuff out. Now there's going to be some things out there. There's static code analysis and things like that, tools that are very valuable that will point to things, will sort of like warn you here and there. And they're going to be helpful for writing better code. But more importantly, or as importantly, I would say, are tools that auto help you auto generate documentation stuff. The old, you know, the I think it was really the first one that was out there. If you go back to Java doc and the ability to just like throw it against a bunch of files and it just creates a nice little documentation website, there is the same thing for every language out there that I know of. I mean, maybe not for like COBOL or something, but there probably still is something out there that'll do it. And if not, go write it because it's not that complicated to document things to a level that a tool like that can easily generate something that then makes it very, very useful for the next person that comes around. And by that, I'm talking about things like your, depending on how your code is set out, it's going to be things like classes and packages and signatures. So you're going to know what is this return? What does it expect? What is the data types that this expects? How does this thing even work? What is it supposed to work? What's the expectations? What are the exceptions? There's some of the error codes. Those things, documenting those are critical. Those are the things that when somebody comes by two years from now and looking at your code, that's the stuff they need to know. It's like, what the heck is this? You got this thing called function ABC. I don't know what that means. Give me some comments. Don't make me go through thousands of lines of code to try to figure this out. And then I miss a couple of side effects or something like that. Document it. The part of becoming a better developer is doing the things that documentation is a sanity check for. It's the kinds of things where you are, if you're documenting your function and you know, I need to document the inputs, the outputs, what are the side effects? What are the data types? What are the expectations? Then you should know what your stuff does. For example, if there's three different types of errors, then you should have somewhere in your code that it's going to kick out a different error code for each of those types of errors. Don't make people find your source code and crawl through that and go searching for, you know, message text or something like that and try to figure out where this error is coming from. Those kinds of things are going to be invaluable to the next developer, which could be somebody like you, but also they're going to help you do a better job now. It really is like a yet another validation, yet another testing form of testing to make sure that what you're writing is correct and of high quality. Now I'm going to sit back and document what I just said while Michael provides his own level of high quality stuff, because I know you've got your opinions on this as well. So I want to see what's your feedback and where am I right? Where am I wrong? So without going too far on my soapbox of user testing and stories, let me add to some of the things you said, because I think you left off a few things. You touched on most of the high points, but one of the things that you didn't mention are readme files or markdown files, files within the application that not just tell you how to test the application, what the application is supposed to do, but how you're supposed to set up the application in a test environment, in a deployment environment. How do you actually get this code from point A to point B so that the users can actually use it? We need to also think about that within our documentation. So documentation isn't just front end, it's pretty much all the way through. You have the front end, which is your user stories. What is the application supposed to do? What are the expectations? What are some of the accepted test criteria? What is the accepted test failures? You know, there's some things within a version of code that might not be fully implemented yet. So certain test stories won't be ready to be tested so that you'll expect those to fail. As you're going through and developing, you're going to be developing with that expectation in mind that, OK, these stories should work. This is what I'm coding to. And when you hand it off to the testers, they're going to look at it and say, OK, I'm expecting this have to work. Maybe this won't work. And then they'll give you feedback and tell you what happened in between. And then finally, when it hands off to the users, if you did it right, you will have release notes or product documentation that goes out to the users. So when the code comes out for the first time or an update comes out, they can look at this and say, OK, how is this supposed to work? So they can read through and it should match what the application does. Also, if things change, they should be able to look at the release notes and say, OK, this changed. So if I go in here, that's why I'm seeing this new feature or why is this new button here or why did this button disappear? That should all be documented from the beginning to the end user. You leave that out, you're going to not set the expectation correctly for the end user and you're going to get a lot of negative calls, emails or feedback that things are not working the way they're supposed to work. So that is in addition to what you said. Now, on top of what you said, some of the things I like and one of the things that in addition to the tools you mentioned, we have things like Bugzilla. GitHub allows you to use a from a markdown or ASCII docs to actually write notation documentation that can be quickly converted into web, nice, easy to read webpages. So you can actually publish that with your code. Some of the other things you can use are like Atlassian tools, which gives you Jira, Bitbucket, Confluence. So you can not just write wikis, but you can combine the wikis with the tickets, the tickets with the wikis. You can even take the Bitbucket, your commits, which can percolate all the way up to the tickets and all the way up to the wiki. So if you do it right, by the time you get to do a release or you publish your code, your document may be self-published for you. So all you have to do is include that with the release notes when you publish the code out the door. And finally, as you're going through this, going back to our last discussion, you want to include all the key players. So as you're working on the documentation, make sure that all the players involved have looked at, or at least are aware of what changes are being done to the software. So that by the end, everyone is on the same page and you can do a sign-off meeting of go, no go, if everything has been met or if issues have come up, is it acceptable to let the code go out the door with changes to the documentation? Now that is very key is that you, you will have more than one type of audience for your documentation and you will also have more than one type of documentation. So I initially focused on the, the code, the developer, but you do have the end users, you may have user, you know, online help or a user manual or something like that. You will probably have, depending on what the application is, some sort of an administrator's guide. So if there's somebody that's administering the system, probably some sort of a build or deployment or install guide. One of the things that Michael like hit on early on is that you want to have a way to, with your documentation, you have to, you want to be able to like plop this on somebody's desk or in their, their computer in some way, and for them to be able to go figure out how do I make this run? How do I build it? How do I deploy it? How do I launch it? What do I need? What's required? And one of the things that I've run into a lot when I'm, you know, when people haven't done that is that there will be all of these little secondary scripts that, or cron jobs or things that are out there that are sometimes critical to the build, but they're not documented anywhere and they're not in the main repository. So check those things in, keep that stuff together. If you've got some little one-off script that you used to migrate data from version one to version two, and anybody else that's going down that route is going to need to do it, then make sure that is somewhere documented, whether you've got like a documents or utilities or whatever kind of folder somewhere as part of that. Or if you have a second repository that is basically here's all of our stuff. Here's all of our artifacts for our, for our application, for our solution. It is critical. I mean, it's, it, those are the things that it feels like everybody can figure that out. Like, I don't know how many times I've seen a node based app of some sort, and they're just based on, but just do a node run. No, there's like, there's all kinds of libraries that maybe are a part of that. And maybe your environment isn't quite like the other. So that would even be part of the testing is take your documentation, take everything, pick it up, put it on a new environment, go spin up a VM, do whatever you need to, but take that whole thing, put it on the environment, follow the steps, test the documentation, does it run? Does it, did you include all the usernames you need to and passwords you need to? And what are all of these config, all those configuration files that you probably have somewhere around there are those documented. So people know what those values are. And even more so what values don't even get used because we do have that on a regular basis. And if you have something that's unused, comment it out or do something, ideally take it out. But if you for some reason need it there, comment it out and say, you know, this I only had set here for testing or for this special bug or something like that. You know, those make sure that all of those little magical things that we do as we're developing to, you know, set things up in a certain way or to address a very specific bug, things like that. Make sure we've got those documented along the way, because that is the stuff that will drive the next person baddie if they don't have it, particularly the build. And I, I say this having in the last 10 years, I've got at least a half dozen projects where it was given to me. The start was no idea how to build this. No idea what all the pieces are. We sort of think this is the source code, but we don't even know if this is complete. We've got these other things over here that we think are valuable, but we don't really know. It could be tied to another project. That stuff shouldn't happen. I don't care who you are. I don't care where you're at in your, in your career progression. You should have some notes. You should have something, even if it's a couple of emails that are just basically here's how this thing runs so that the next person can at least have a starting point. I will kick it back over to you while I take a deep breath after that little bit. So my final thought on that is regardless of where you're doing the documentation, try to make sure that you move as much of the documentation to the code level and read me files and comments to the code. If you're doing APIs add swagger, but if you put it all at the code level, especially if you're doing unit testing or integration testing in your code, your test should also self-document some of the user stories. So if you do all your comments correctly at a push of a button, you should be able to generate those documents you need for the release documents, for the user documents, for the deploy documents. It's all at the code level. This way, as things change, it gets committed and you have version history of what's going on with your code. That's not to say using things like the wikis and that are bad, but at the end of the day, the code is essentially the law. The code is what is the truth. Everything else is secondary. So if you put it in your code, it should be your Bible. This should be what it is that your code does. So if you do have a wiki page, it can get stale, but if you do it all in a read me file, you can still point the read me file to potentially the swagger page. If you're running locally QA, whatever, but you could still do it all in your code and then commit it. And it's all there. It's all at the ready. So the next person that comes in should be able to easily pick it up. It's great for training and it makes our lives easier as developers. Yeah. I like to think of it as you could, if you've got your car and you've got a user's manual for your car, there's a big difference from that user manual sitting in your office somewhere on a desk versus sitting in like the glove compartment of the car. And that's often what happens. We have all these little extra things, sometimes big things that are external to our application, but our core requirements and those things need to be documented somewhere. It's things like, Hey, this only runs on windows 3.0. Okay. Somebody needs to make sure that it needs windows 3.0. Those kinds of things should be there. Even if you don't include that entire environment in include those notes, say these are the things you need to do to set up the environment for success. One things you can do to set up our environment for success is to give us feedback is to send us emails at info at developerneur.com. Leave us comments out on YouTube or out wherever you get your podcast or on developerneur on any of our articles anywhere. We've got over a thousand articles out there. Feel free to throw stuff out there. We will respond. If it's a spam, we obviously won't. We'll like delete it and move on. But if it's something useful and for you guys, I know it's going to be useful. So, you know, reach out to us, offer us any suggestions, comments, questions, all of that kind of stuff. That is what we look for because that is what we use to help build future episodes and even seasons. The season is not done. We are chugging along, but we are not done yet with the developer journey. So we will come back next time and we will continue to do that. As always go out there and have yourself a great day, a great week. We will talk to you next time. Thank you for listening to building better developers, the developer podcast. You can subscribe on Apple podcasts, Stitcher, Amazon, anywhere that you can find podcasts. We are there. And remember just a little bit of effort every day ends up adding into great momentum and great success.