Architecture Decisions

I’ve spent multiple years in a wide array of different teams. One thing that separates prepared teams over chaotic ones is, in a nutshell, documentation. This seems to be known by most of those teams I’ve worked with. Yet, through a series of unfortunate events or decisions, documentation is not prioritized. But there’s one pretty easily way to bring documentation to your team without dedicating tons of team hours to it: choose tools and technologies that already have good documentation.

In this field, we can become distracted by shiny new things. Whether that be trying to create our own security framework (in 99.9% of cases, please don’t) to using a cool new language, we often find ourselves stuck with a tool that is more trouble than it’s worth. Ramp up time for new employees tends to get strung out, standardization turns into passive aggressive changes to their ‘wrong code’ per commit, and future employees curse your name as they try to fix the Pandora’s box you handed them. All because of poor documentation.

If given the choice between two fairly equal choices, choose the one with better documentation. You can send your new folks to it to get up to speed quickly. Standardization will already be set, so agreements can be squashed more easily. Future employees have something to lean on when navigating through legacy code. Everyone is much happier for it, even if you couldn’t implement the shiny thing.

To note, this isn’t a blanket rule. In rare occasions, people are in the right place to write documentation for their project, or create that awesome security framework that fills a gap. But in most cases (especially if you’re working on enterprise apps), side with already-documented tools. I’ll thank you for it in advance.

This is but a small snippet, and is based off my own experience and conversations with coworkers and leaders in the field in my area. Tell me in the comments if you’ve got a different perspective.