In the recent weeks I have come across at least two web solutions that are in a very bad shape. The product is fine and the customers happy. The company behind is profitable and the competition is manageable. But what is the fuzz then about?

The solutions are poorly documented. Dead simple and that’s dangerous for the product and the business. Note that, it is documentation in a very broad sense, all the way from traditional documentation in the source code and overview of the functionality in the major files to a document listing the important selling points when approaching a customer. However, it seems that the closer we get to the sales part the better the documentation gets. The interesting fact is that the sales documentation will never save the solution if it breaks and just as importantly it doesn’t help the developers make the right decisions when upgrading the software. Both things are extremely important, and more web solution owner should take these things seriously.

Many entrepreneurs with great ideas for web products team up with a developer in order to make the product possible. Often it is a single developer, a dedicated and skilled one of a kind, but as in most case do developers focus on the code and not the documentation. Even though, during their education the documentation part was just as important. Nevertheless, the documentation is lacking. The code, the design and reaching the deadline gets the focus. And that’s natural.

Prior starting a project you might document the overall goals in order to communicate your idea to the developer. However in some cases, the documentation might exclusively be oral, hence impossible to relay to new people – which bottom-line is the nice part about documentation. Additionally, the developer might have sketched a database diagram or even written some use cases or similar. But remember that documentation isn’t documentation unless it matches the actual product implementation, so documentation should be updated when the solution is finished and every time something is changed.

Imagine that your developer leaves for trip around the world and you are on your own. You might need a new feature or the product breaks. The new developer assigned with the new tasks is in real trouble – and so are you. Even with the proper documentation, it might take a developer a week to understand the project before trying to fix the problem – assuming a relative small code base and simple functions. Bigger systems and increasing complexity in the features will dramatically increase the time needed in order for a developer to grasp the code and recommend a solution that fits the existing solution and not just fixes the problem – it’s an important distinction. Documentation will reduce the time needed and that is crucial if your solutions is down and it has a business critical function for your customers.

Keep in mind that documentation isn’t just something the developer should make. Some of the documentation relates to sales and the processes around downtime and informing your customers. Take part in the documentation process – you’ll need anyway as soon as you need to expand your business. And finally, note that sales documentation, vision and overall explanation of your product is key for a developer as well, if he/she should make the right decisions for your solution.

So reflect on the title of this blog: Does your documentation kill your product in the long run? Do you have a web product that lacks the documentation?

software, documentation, software documentation