How To NOT Suck At Software Engineering Documentation

screw it documentation in general is totally not worth it don't invest any time into it today we're going to talk about documentation and software engineering and documentation is something that you can't really Escape in software engineering even if you're not thinking about it in the traditional sense at a bare minimum the code that we're writing as software Engineers is some type of documentation now when it comes to documentation I don't think that anyone's really disagreeing that having information that we can go back to and review look things up be able to search like that's not a bad thing having that kind of information is really valuable but unfortunately we can't really seem to agree on how much time to invest and the best ways to go about documenting things so in this video I'm going to talk about five different types of documentation we're going to look at onboarding documentation troubleshooting design documents planning and work item style documentation and then of course code itself now before I dive into the details just a quick reminder to check that pin comment for a link to subscribe to my weekly software engineering newsletter it's totally free and there's lots of awesome stuff every week so the first kind of of documentation I want to talk about is for onboarding and this could be onboarding to a team or a company and it might depend on the size and the the different scale of the company that you're working at but if we think about it strictly from a team perspective this onboarding documentation is something that someone could refer to if they're about to join the team what kind of resources can they look at to start feeling like they understand what's going on getting their environment set up understanding the software and the different tools that you're using on the team having documentation like this is incredibly valuable for speeding up the process for someone to get into the groove working with you instead of them plugging in a computer and trying to figure out how they can even get the code checked out to their computer or how to even log into the shared chat application that all the developers are using to talk having documentation can help them get up to speed super fast and get the right answers for the things that they're going to encounter as they're on boarding and something that's really awesome about onboarding documentation depending on the scale of your company is that if you have multiple teams and they have their own slightly unique onboarding there's going to be common elements so for example there might be a common way that all of the different developers are using to chat maybe it's slack or teams or some other type of chat application maybe there's a common way that the repositories are accessed and all the build tools and things like that for example when you have shared documentation like this what's really awesome is that it can go into a common spot and that way it can be maintained in common but I just mentioned maintenance and that's going to bring us to some of the cons of working with onboarding document the first challenge when working with onboarding documentation is that someone's got to started it just doesn't show up out of nowhere then the other big challenge with onboarding documentation is that it's almost always out of date but interestingly I think that something that we can do to improve this it doesn't perfectly solve it but I think it's a really good balance is getting the next person to on board to either create that documentation from the start or to be able to improve and fix the things that are broken or out of date as they're going through through it think about it realistically how often do developers on the team have time to go sit down and work on the onboarding documentation it's going to lose out in priority compared to bug fixes features Tech debt all sorts of things on a regular basis but it is really important so if someone takes the first hit and maybe it's the next person coming on if it hasn't been created you have someone kind of pairing up with them to walk through the onboarding and you say hey look as you're going through this start documenting stuff and that documentation might be pretty rough to begin with but that's okay because the next person that comes on board you say hey look we got some onboarding documentation it might be a little rough your turn to go through it and improve it and as this cycle continues and as more people are joining the team maybe other people are leaving new people are coming on that means that there's opportunity for this documentation to get refreshed it's not the only mechanism you have to keep it up to date but I feel like it's one of the most natural and that way you're not constantly trying to set aside some time that it's probably going to be de prioritized for other things the next type of documentation that I want to talk about is troubleshooting documentation and where I work at Microsoft we call these battle cards and the idea behind troubleshooting documentation is that as people are working through different challenges for us it's a as on call Engineers or as Engineers running the service when we have teams reaching out to us asking for help we have these battle cards is what we call them to go look up different scenarios that Partners might be encountering and using this type of documentation our battle cards we're able to go check out these different scenarios and go okay let's go step by step through this and figure out how to problem solve what's going on for us these battle cards are incredibly valuable and that's because the breadth and the depth of the systems we're working with is tremendous it's basically impossible for any one person to know all of the things that could be going on so then as an on call engineer getting some information from the partner about what's going on then keyword searching that through the battle cards is a great way to find scenarios that they can start to walk through now there are a couple of challenges as you might expect with this type of documentation and they're kind of similar to what we talked about with the onboarding documentation the first is that this kind of stuff can go out of date there might be so many different scenarios that we try to capture in the trouble shoting documentation that as systems are growing and evolving there are these scenarios that have been captured and they have step-by-step guidance for how to problem solve and fix things but it's no longer applicable when that kind of thing happens you can really start to lose confidence as an on call engineer trying to problem solve things when you're going uh-oh the knowledge base we have isn't working so well and the other reality especially in the space that I'm operating in and you might be able to relate to this is that there are so many different scenarios for things that could go wrong that there could be really big issues or things that seem really important and we don't have that documented so these are a couple of really big challenges with troubleshooting documentation but it's not like I would say screw it documentation in general is totally not worth it don't invest any time into it instead I think that there's a balance to be struck and that's the case for most things I find for this type of documentation when you're working through different problem solving scenarios I would say try to update it as you go if you're finding that stuff's out of date be the one to go improve that for the next person if you're finding that a scenario is missing well when you finally figure out how to problem solve it and fix it be the person that documents that and has great steps for the next person to come across it now if you've watched my videos on Tech de and heard me talk about tech Deb and refactoring things this is the perfect type of example of that boy scout rule in my opinion where as you're going through stuff you're just making sure it's a little bit better for the next person that's coming through and a question that I want to leave you with is that for this type of troubleshooting documentation if there's step-by-step information about how to troubleshoot it and then how to repair it could this stuff just be automated why do we have it documented in the first place if we could have automated systems in place to correct it for us I get that it's probably not always that easy but something to think about now the next type of documentation that I want to talk about is design documents and these are really awesome I think they're a great way for engineers and other participants other stakeholders to be able to get information down on paper and it doesn't have to be literal paper I know we're in a digital age here but the idea is that you get your thoughts put down you have your diagrams you have the different pieces of the system that you're trying to put together and another great thing is that there's so many awesome collaborative tools so if you're working on a shared document that means the design can get put together and you can have the stakeholders participate and collaborate often in real time or asynchronously in working together at Microsoft I've seen different variations of this ranging from the one pager which is often sometimes like a two or three pager but something pretty basic and then all the way to really in-depth like you know many tens of pages of design documents illustrating how a system works and how it should be put together these often go through different phases of iteration where people are doing some ideation in the beginning and then from there getting some feedback getting some criticism iterating on that and redistributing to get more feedback once that's addressed and again what I really like about this is the collaborative nature that often comes with it as well as having visibility for all of the stakeholders that might be interest in what this design is the other great part is that for people joining the team or they're coming onto this project at a later point you have a design to refer to there's a bunch of documented information about the system but there's a catch and there's a catch to all of these which is why I want to talk about it when you have design documents and you start building things off of that design doc odds are just like most software things are going to change in real life once you start implementing things there's going to be things that you discover that you didn't plan for as hard as you tried and that's okay and you're going to need to evolve and adapt to those things then there's going to be external factors as as well so even if you plan perfectly these external factors you might have to rep prioritize and might re-evaluate how your design is implemented now the challenge is that if you have this implementation that's being carried out you also have a design dock that you were having to go along with this design so if that's getting out of sync with it not only you're going to have to fix your design as you're going but you have a design dock that you have to also go maintain to match that now it's not really that hard but the point that I'm making here is that it's a bit of extra work it's a bit of Maintenance that you have to do alongside your design and if you're not taking care of that that's a little bit more dangerous because now you have this design dog that's no longer matching with the system that you've built and that means that people are leveraging that to try and learn your system all of a sudden they're going hey like I learned this and I assume this about the system because I read it in the design Dock and that's totally not what it does so just something to keep in mind I think design documents are awesome I think that there's a balance between how much you put into that and how early you get people collaborating as well as having to think about how you maintain them as you're building out your implementation the next type of documentation that I want to touch on is related to planning and the work items that the team is focused on now I know that these aren't necessarily the exact same thing and where you work you might have different systems to to organize these different thoughts but I wanted to group them together because I think they're similar enough in how I would approach them so planning documentation or the work items that the team is taking care of I think that those are a great opportunity for you to document things like customer asks so not just having the title of a story or something but being able to document why a customer's asking for something some of the assumptions that you're making at that point in time to get you to the point where you're making a decision about why you're trying to do this for the customer that could look like feedback for a feature request or maybe they had uh you know feedback about how a competitor was operating anything like that but extra information and having that documented I think could be a great resource for looking up at a later point another great thing that you get out of this is tracking both your successes and your fails so for example if you're building out those designs from your design document have those documents linked into the work items and the planning that you're doing have those accessible for other people to access if you're carrying out that work and it's changing over time and you need to get that updated that's a great opportunity not only to update your design doc like we just talked about but also to try and document what you're learning from that experience and recording that in your work items and having that available for next planning I think can be incredibly valuable and your fails as well I mentioned recording your fails because I think that that's really important too A lot of people don't like to talk about work items that they're trying to accomplish and for whatever reason it's something that's not going to get finished it might be something externals come up or we made an improper assumption but it feels like a failure and that way people don't like to talk about it they like to hide it and not draw attention to it but I think when we fail at things I think it's incredibly important to try and reflect on them try and learn something because a lot of the time it's not necessarily just something you did wrong it could be external factors it could be things that you learned that we did not assume properly in the first place so why not document that taking your learnings and then transcribing them it's such an awesome approach to be able to have that captured and have people in the future be able to reflect on that and use those learnings as well now there's drawbacks to this type of thing as well and I'm not trying to say again like don't do any type of documentation for your planning or your work I do think that that's important but some things that make this really complicated are when you have different types of systems that are used together to try and capture similar types of information or the exact same information in different spots this could occur because you have different stakeholders that are familiar with different tools they integrate with other systems as well but both parties you know both sets of stakeholders need that information the systems that we use for tracking this kind of stuff even if it's the same system often have discrepancies in how things are tracked so if you've used things like jira or Azure devops there are things like epics stories bugs tasks you name it I've seen teams where all they do is they use the bug type and everything even if it's a feature it's just a bug because they don't care about the granularity their team doesn't need it to work on I've seen other teams where they're hyp specific about it and everything has to have the perfect hierarchy in order for them to be able to function and Tackle their work properly now this can get a little bit messy if you're trying to get different groups of people work together and they have different expectations about how that stuff is tracked so just something to keep in mind it's not a total deal breaker but it's just a little bit of extra complexity that can come out of this type of documentation and finally and honestly this is the thing that drives me the most nuts with this kind of documentation is that it's the perfect opportunity for bike shedding and if you're not familiar with that term it's where people are really focused on the stuff that really doesn't matter in the grand scheme of things I've seen people waste so much time being very pedantic about how things are captured in the documentation that we probably could have finished a chunk of the work by the time they've agreed on how something should be said and I get it being clear in this type of documentation is really important but I think at some point the focus is lost and we're losing the point of having the documentation in the first place because it's supposed to help us make progress and if we're spending so much time on it and we're not able to go accomplish those things as a result I feel like that's kind of working against us maybe it's just me but I see this come up a lot where I feel like we could be moving on and trying to make progress on the things that we're talking about and finally the last type of documentation that I want to talk about is code now software Engineers spend a significant amount of time reading code we like to think that we're spending all of our time writing code because that makes us feel productive but the reality is there's a lot of troubleshooting there's a lot of figuring out where we should be integrating our parts of the code and as a result we need to be reading tons of it that means having very clear and concise and expressive code is really important for us as software Engineers so we don't have to waste a lot of extra effort trying to figure out what the code's trying to tell us now something that's debated a lot is comments and code and personally I feel like there's a happy medium because I would say that no comments is probably not the best but I think a lot of the comments that we see in code are very redundant when you have redundant comments you end up creating maintenance or you're creating problems or both so when you have comments that are redundant for what the code is doing if that code changes you need to change the comment as well to reflect it and if you don't this is where you have some really crappy times cuz people are reading the comment reading the code and they're not aligned so what's supposed to be happening personally I think comments and code being reserved for things like explaining why a decision is made because I don't think that can always be captured in the code is a good use for comments having comments that say this if statement does whatever or I'm looping on this range I don't think really help but but if you had to write a little bit of weird code to make something work and even after pondering how you can make it clean and nice and refactored it's still not going to land properly I think leaving a comment to say hey look I had to implement it this way because of these restrictions you're kind of giving a warning to the next person coming through I think that can be very helpful but this is something that gets debated an awful lot and I think it warrants me creating a video dedicated to what I think good comments look like and what crappy comments look like too but that's going to wrap it up for this video on documentation the takeaway that I want you to have is that some amount of documentation I think is incredibly important but I do think that you need to balance that with the thought around how you're going to maintain it documentation does not get maintained for free so thinking about ways that are low effort low amount of pain to be able to keep that documentation up to date as much as possible so that it's accurate and usable I think is a win so thanks so much for watching I hope you found this a little bit insightful and you can apply some of this to the documentation that you're doing on your teams thanks and I'll see you next time