Unrelated image from pexels.com to make this post look nicer in social media shares.

Today’s tip for becoming a better programmer while still having a life isn’t just good for you, it’s good for your whole team. That tip is documentation.

I know, nobody actually likes doing documentation. Fortunately, I’m not talking about dry design docs or endless specifications, I’m talking about a simple wiki (or whatever works for you), written by you and your team for you and your team. It doesn’t have to be polished, it doesn’t have to be formal, it doesn’t even have to be spelled perfectly. All it needs to be is correct and understandable. The idea is to explain things just like you would to another dev on your team, not to waste hours proofreading.

Great, but what should you document? In short, anything you’re going to want to know later. Especially useful things to write down are why architectural decisions were made, how parts of the system work at a high level, guides to testing certain features (great for complicated payment provider integrations, not that I’ve been fighting with those), and especially guides to setting up your development environment, whatever that thing is that you forget every time and have to look up again or ask someone about.

Just saving yourself time relearning parts of your codebase will help you get things done faster, which is basically being a better programmer, but explaining things (even if you’re writing to yourself) helps you understand them better. Explaining something forces you to think about every little detail, and putting something in your own words helps it stick in your brain – it’s the same principle that helps you remember things better when you take notes on them, whether or not you ever look at those notes. The better you understand your codebase, the better decisions you can make about how to add new features or fix bugs.

As a bonus, reflecting on why you made certain decisions and being able to go back later and see if the reason you did things the way you did holds up over time also makes you a better developer. You don’t even need to make a special effort to do this, if code gets used it gets changed. All you need to do is wait, eventually you will have to revisit the code you documented and by the time you do that, you will probably have forgotten the details and will need to go look it up in that handy wiki you created :)

Writing things down also helps you get that answer again without interrupting anyone, and the less you can interrupt teammates the better considering how expensive interruptions are for programmers. I couldn’t find a hard number, but I feel comfortable saying that it takes at least ten minutes to get back into a complex task like programming once you’ve been interrupted. It can be even worse if you get interrupted at just the wrong time. I have a terrible time getting into a task when I know I’ll have to stop soon for a meeting or appointment or whatever, which means an unfortunately timed interruption can kill a solid half hour of productivity even if it only took a couple of minutes to deal with the interruption itself.

All the benefits you get from making knowledge about your code available and searchable also apply to your teammates. If you just document how to set up your development environment, that can save hours every time someone has to set up their environment whether it’s a new employee starting or a long time employee getting a shiny new computer to replace an old one. It’s even better for everyone around you if the whole writing things down idea catches on – then they also get the benefits of explaining things and documenting the particular things they forget and need to look up as well.

And best of all, this is another work thing you can do at work that has no effect on your personal time.