Working Software Over Comprehensive Documentation

This is Building Better Developers, the Develop-a-Noor podcast. We will accomplish our goals through sharing experience, improving tech skills, increasing business knowledge, and embracing life. Let's dive into the next episode. Hello and welcome back. We are continuing our season where we're looking at the Agile Manifesto and Agile development processes in general. We've worked our way through the 12 principles. Now we essentially step back and we are looking at the overall four, there's really four key items that they look at. And these are things that are of greater value than some things that we use a lot that are of lesser value. This episode, we're going to look at the statement that we value working software over comprehensive documentation. Now we have looked at the idea of working software as being a primary output of a software project. At the bottom line, that's what we're doing. We're solving a problem. So we have a problem. We need to provide a solution. That solution would be working software. Now working software, however, is not something that only shows up at the end of a project. We can, as we've already discussed, we can actually produce working software along the way in almost every project, unless it's very, very simple. That would be, let's say it was an application to add two numbers. There's really not a point to have working software other than the end result. If it's just, you know, a couple lines of code or something like that, you're just done. It's just that quick. But if it takes you even, really even days or more to create software, then there's at least some level of working software that you're going to be able to build along the way. To some extent, that is the whole concept of unit testing, is that we have these units of work that are complete, we'll say, that we can do. And they can be tested in and of themselves. Now you're not getting the full system test and things like that. But there's, no matter how you slice it, there's going to be ways to produce some level of working software. No, this point is not just, hey, we're going to do unit tests and we're going to have these units that work. This is working software, not just working code, I guess, if you want to look at it that way. So we're talking about actual, something with an application, something that can be applicable to some level of the problem or some aspect of the problem. And it may be ancillary things like user registrations and logins and logouts and maybe even help systems and messaging and things like that. But those are working software. They may not get the big problem that end result solved necessarily. But there's going to be steps along way. There's going to be things that users will do or experience that we can provide before we get to the end. Now, this would be of probably all the points, the one that is the biggest sticking point for pro and anti-Agile people that are not fully aware of what Agile really is about. Because I have come across more than a few people that consider Agile to be anti-documentation, that Agile doesn't document. You don't document stuff. Or it's, we'll say self-documenting, which is that latter point, self-documenting is not incorrect. That tends to be the shortest path to address the fact that there is a value in comprehensive documentation. It's just making documentation in and of itself a goal is not always the best approach. I say not always because there are definitely situations where you need a user's guide, a user manual, an administrator's manual. There is definitely, for example, in an API, there's a lot of value in a comprehensive document to tell you how to use it or what the details are in using it. So again, this goes back to one of the things we're going to emphasize in these couple of episodes where we focus on these four points. The point is not that there is no value in the things on the right, comprehensive documentation in this case, but that there is greater value in the thing on the left, working software. I don't know that that's something many people would argue. If you get to the end of the project, can you jettison working software or comprehensive documentation? Really, you can't just throw either of them out, but if there's one that you're going to cut corners on, it's probably going to be the comprehensive documentation. I don't know many cases where that would not be the situation. That would not be the selection. So this again is where we take, really you almost have to look at as we take a 1A and a 1B, some very valuable things that need to come out of a project. Working software, number one basically of these two, but 1A, if that's 1A and 1B, comprehensive documentation would be the second piece. We have to be able to pass this on so that people can use it, so that people can maintain it, people can extend it, and all those other things. So just because, again, because it has lesser value does not mean that we can skip it. And it's comprehensive documentation, not documentation. This isn't saying that documentation has value. This is saying comprehensive documentation, fully documented. So when you think about that, when you look at it as a 1A and a 1B, I think that really flips on its head the idea that Agile is not about documentation. Not only is it not about it, it is one of the core things that you need to have to complete a project. If you look at these eight items, it's these four points where there's a 1A and a 1B, these are things that you essentially have to have, 100% have to have in order to get a successful project. That means comprehensive documentation. That means that we need to have user's guides, administrator's guides. We need to have comments in our code or code that is easily readable and understandable. We need to have comments in our commits. We need to have an audit trail of what did we do and how did these features and things get into the system. We need to document how we deploy it. We need to document what was tested, what was the result, what was fixed. These are all key things. And if you look at how Agile approaches like Scrum have evolved since this manifesto came out, you'll see that they do include all of those things. When you go through a sprint, it includes testing, it includes documentation. Most places that I've been are very big on making sure that there is, it's not necessarily a document by itself, but there are tools to help you with that documentation. There are development standards that ensure that documentation is done as we build this. Not just documentation, comprehensive documentation. You don't skimp on the documentation. You don't just throw a bunch of templated comments out there and let them get out of sync with the code. That actually points us to one of the things that I think comes up rather frequently if you're in a well-functioning Agile team, which is the idea of technical debt. If you've been an experienced, had any experience with that, you probably understand that documentation tends to be, and this is especially in my experience, tends to be the biggest area of technical debt. We get stuff done, we put it together quickly. We're not 100% sure maybe that that's exactly the way it's going to be done because we're putting some stuff in front of customers, we're testing it out, we know it's going to change, or we assume it's going to change. We leave some wiggle room within the documentation. There's some things that we haven't fully documented out because we're pretty sure that's going to change and we want to save the documentation so that we can do it once and be done, hopefully. Now, there's arguments against that, one of them being that that's producing technical debt. At some point, you can get buried in technical debt and end up having to have a release that is just catching up. That's not really pushing any, not really moving the ball forward as much as saying, we've got all this extra weight we're dragging, we're going to cut back on some of that weight so we can move the ball forward at a faster pace in the future. So documentation is not something that we get to just ignore. It's something that not only do we need it, it has to be comprehensive. That's, I think, an often overlooked aspect of the Agile Manifesto. It does not disparage the things that we know we need to do as part of a project. It embraces them. It says that, yes, we will hit road bumps. We will need to document things. We'll need to test things. Requirements will change. And that's not only a bad thing, that is possibly a competitive advantage. It's a whole idea of Agile is that we have these things we have to do. These are all required steps along the way, and we're going to find the best way that we can make sure that those things are addressed properly. Now, working software over comprehensive documentation, I think, is where you get the idea of self-documenting code, or better yet, maybe even a self-documenting application. Now, this is back before the idea of UX user experience was as settled, I guess, as it is now. It's very much an accepted part of software development. Go back a couple of decades, not so much. It was there. Don't get me wrong, people did. User testing and user experience was a thing, and people worked on it, but it wasn't as evolved as it has become now. But I think working software, and particularly when you pair it with comprehensive documentation, is an interesting pointer towards the idea of having a user experience that is sublime, a user experience that is flawless, that is very intuitive, so that you don't need to document it. If I asked you to go get mail from your mailbox, there's not a document for that. You know where the mailbox is. You know how to walk. You know how to open a mailbox. Even if you've never gotten mail from your mailbox before, or my mailbox, if you showed up at my house and I said, hey, can you go grab the mail out of the mailbox? You would pretty, I mean, it's not intuitively, but you would know how to do it, because all you would need to do would essentially be point it to the mailbox, and you can figure the rest out. That is the perfect user experience from a software point of view, from an application point of view, something that they just know how to use it. Maybe it's as simple as, think about it, especially a lot of tablet and mobile apps. There's an icon that you click on it or double click on it to start the application, and then you use it. Now, it could be a game that's very simple, I don't know, tic-tac-toe or something like that, but even then, there's rules to tic-tac-toe, so that you want to have some way that you incorporate that documentation into using the application. Now, it can be as simple as having a crud type application where you're doing data entry, you're saving stuff, and you just really have really good labels and maybe some context related help or hover bubbles or things like that, so that a user that starts up your application has sort of guided through how to use it, or it's such a natural experience. It's intuitive. That the documentation is not necessarily needed, and that's where this points to, is that you can create very good, incredible, comprehensive, thorough documentation. However, if instead you can have a better application, an application that removes the need for such thorough and comprehensive documentation, that is the path of more value. That has greater value, and I don't think that's arguable in too many sense. I don't think too many people are going to sit there and go, you know, that's not right. I would rather have comprehensive documentation. Just the idea of it being, it's a separate thing. Whether it's a PDF or a physical manual, if you're using software and you have to refer to the manual, you have to change gears and fire up that, open up that PDF document or that Word document or go grab that book off your bookshelf. Instead, we want to focus on the working software. I think when we look at these four points, that's part of the underlying message that they convey, is that working software and comprehensive documentation are two things that we have to have, and they are related. If you think about all of these four points, that's what we're going to find out. As these things are related, and I think we need to make sure in producing good software that we make this connection between these things that are related. Now, some of them are very obvious. Responding to change or following a plan. Well, obviously changes come or changes to your plan, but this is one that I think we don't always make the connection. The comprehensive documentation is part of the user experience for working software. When you look at UX, we think about the actual user interface. We think about the neat controls or aesthetically pleasing interface, colors and buttons and labels that are meaningful and things like that. But this does extend to documentation. The solution we provide is not just the application. It is also the documentation. It's not just the application. It is the other pieces, other deliverables that we provide that tell you how to use that software. What happens when something goes wrong? What are the expectations? All of that is mixed into the idea of working software, of a solution that will satisfy the customer. Challenge of the week for this one. When was the last time you sat down and comprehensively documented the work you were doing? The source code that you were creating, that you put comments in. How about the commit comments? When you commit to version control, do you just scratch something simple down or do you have something that tells a story of how this thing got built? Are there maybe some adjustments it would be worthwhile for you to make so that you do kick your documentation game up a notch? Since you get better in that aspect of delivering software. It's tough. It's not, I think in most cases, it's not our natural approach. We write code. We don't write documentation. I think a lot of people would say. To some extent, that's true. That's our strength is not usually going to be in writing documentation. It's writing code. But sometimes we have to go to address some of our weaknesses and make use of some of our lesser skills in order to provide the product that satisfies the customer. That being said, I'm going to hope to satisfy my customers by sending you off on your merry-go-round and as always wishing you to have a great day, a great week, and we will talk to you next time. There are two things I want to mention to help you get a little further along in your embracing of the content of Developineur. One is the book, The Source Code of Happiness. You can find links to it on our page out on the Developineur site. You can also find it on Amazon, search for Rob Brodhead or Source Code of Happiness. You can get it on Kindle. If you're an Amazon Prime member, you can read it free. A lot of good information there. That'll be a lot easier than trying to dig through all of our past blog posts. The other thing is our masterminds slash mentor group. We meet roughly every other week and this is an opportunity to meet with some other people from a lot of different areas of IT. We have a presentation every time. We talk about some cool tools and features and things that we've come across, things that we've learned, things that you can use to advance your career today. Just shoot us an email at info at Developineur.com if you would like more information. Now go out there and have yourself a great one.