Document Like a Cool Kid

There’s no getting around it – finding a developer who likes writing documentation is about as easy as finding a document that likes to develop. Ask any software engineer how much time they truly spend documenting their projects and you’re sure to get a mumble and a glance at the floor. That’s right – like the computer lab in high school, Confluence just isn’t where the cool kids are hanging out.

In my experience, documentation typically comes in a few less-than-desirable flavors: outdated, useless, and outright absent. Yikes. But as often as we curse those “other” folks for not documenting their REST API that seems purpose built to reply with 400-level errors, we’re likely doing a bit of procrastinating ourselves.

“C’mon man – another CORS error? Fix your headers!”

I’ve been there. You’ve been there. We’ve all been there. But even if it feels like we’re always on the receiving end of poor documentation, I imagine you can likely admit to yourself in a rare moment of vulnerability that you, like me, may occasionally not live up to your own standards.

I’m right there with you. I took “Java 220” in college, not “Documentation 220”. I love coding and the problems I get to solve each day, but I don’t want to relitigate the entire process for a fictional person on the other end. I want to code!

But documentation – in code comments, architecture diagrams, and everything in between – is an essential piece of good digital citizenry that we’d be utterly lost without. It’s the breadcrumbs for our future selves, the keys to the castle for our team, and the get-out-of-jail-almost-free card for those poor souls who run into trouble. More readable than stereo instructions and more detailed than those IKEA picture manuals, good development documentation is critical. We’re looking at you, LӦMMARP.

‍

‍

Of course, our beloved customers also play a huge part here. They’re likely to care about the end result, not the instructions passed around among developers, so the time needed to properly document is often sacrificed at the altar of scope creep. And that’s too bad, because that’s how technical debt mounts, which inevitably leads to more.

So, duly enlightened to the necessity and virtues of solid documentation, let’s take a look at a few ground rules to work documentation into our daily routines and promote it to its rightful place in our crammed, cluttered work lives.

Make it Accessible

Use easily accessible and low-cost tools to centralize documentation and ease the friction. Our small teams tend to use Confluence for general knowledge management and collaboration, while we turn to Jira for ticketing and project management. Both are Atlassian products and are free for teams with 10 or fewer users. Free is my favorite price!

Make it Team Culture

Create a team environment where documenting code isn’t just expected, but celebrated. After all, high fives aren’t just for Borat. Keep your team members honest and invite them to do the same. Champion keeping it up-to-date with a tone that’s easy and accessible for the audience, and always make sure you’re revisiting it regularly.

Make it Normal

Documentation is part of the work. Period. Ensure that the documentation paired with committed code has been updated. This means that when setting roadmaps or scoping the work, time for documentation is budgeted in and prioritized as a component of defining the finished product.

There are many ways to document, but skipping it should not be an option. At Bitwise, our absolute favorite thing to do is to deliver beautifully simple solutions, with code that’s readable and easy to follow. But even our best code deserves excellent documentation, because that’s how we fulfill our responsibilities to ourselves, our teams, our customers, and our community.

If you’d like to talk with us more about our services and our attention to detail, reach out anytime! We’d love to give you a high five.