So What Does This Button Do?

Part of 10 reasons why Software Development projects fail series.

In the world of software development, it’s important to be agile and move fast. However, technical documentation is also important. Document, document, document. Without documented code, you might be facing years of technical debt, as people try to figure out what different buttons do, and what functionality is really present in the software that you have just created.

Here’s an intuitive, real-world example of why project documentation is so important: take a look at the remote control for your living room TV set. Do you really recognize half of the buttons on the remote? Do you know how to use them? (Even the button at the very bottom that has some symbol on it that looks like it’s from an ancient language?) Yet, all of those buttons, no matter how obscure, were considered a “good idea” at some point of the design process. Most likely, these “features” were actually a “bug” that nobody bothered to figure out. As long as everything worked at the end, it was probably safer just to ignore the buttons that seem to do absolutely nothing.

That same sort of confusing functionality is also part of many failed software projects. Nobody really knows what certain buttons do, or why they were even included in the original design. Maybe a developer decided to add a test feature after receiving a panicked email message from the CEO, but never remembered to remove it later.

by Katerina Limpitsouni

So what type of documentation should you include for a software project? The current best practice is to document every step of the development process, from ideation to design to execution. And this documentation should be easily navigable for others, not just filled with a lot of cryptic, insider notes that are impossible to decipher.

Of course, the common complaint from developers is that too much documentation is going to slow them down. If they are in a sprint, do they really want to slow down and take the time to add a few notes about what a line or two of code does? Of course not. Time constraints are a very real feature of software development projects, so it’s easy to see why there can be some internal resistance about documentation and tracking.

But here’s the thing — as much time as you might spend moving forward, you are going to waste more time going backwards. In other words, the whole testing and de-bugging process is going to be a lot smoother and easier to navigate if the right documentation is in place. When you are de-bugging software, you absolutely need to know how things work, and the internal logic of each new piece of functionality. That’s especially true for large-scale software projects, where searching for what just went wrong can sometimes feel like searching for a needle in a haystack.

bt Katerina Limpitsouni

You can think of technical documentation as tiny breadcrumbs that you leave along the way for others. People following behind you will have a trail to follow that is well marked, consistent (all the breadcrumbs are from the same loaf of bread!), and easy to decipher. Good documentation always facilitates accurate project tracking, enabling you to deliver a final product on schedule and on budget.

Hey! I’m Tomer, an entrepreneur and maker. You might know me from Mevee, Crane, and Shots, among other products I’ve launched! This article is a part in a larger series I’m writing mostly based on my experiences, and is largely made of my and my team’s opinions.

I hope this helps you to avoid making the same mistakes I did, and remember to keep shipping!