The Business Case for Proper Documentation

In a software development project, documentation is often an afterthought. In this post I’m going to explain why it’s hazardous to the long-term health of your project to delay creating proper documentation.

At Optimus, we see this problem constantly as we inherit software developed by other companies or by a client’s internal team. When that software doesn’t have proper documentation (requirements, user stories, test cases, technical design, etc), we have to spend significant effort in reverse engineering the solution. With properly documented software, the ramp up time is significantly reduced which allows development to start sooner saving substantial development time.

Below are the five reasons we recommend investing in proper documentation.

Reason 1: Teams Change and Grow

One of the key reasons to create proper documentation is that it’s almost inevitable that over time the team will change, grow, or move on to other projects.

This kind of team movement will lead to time wasted in trying to reverse engineer the software, understand the original requirements, and get a grasp of where the functionality currently stands. Even on a stable team, team members will work on different pieces of the application over time and then forget exactly how earlier modules were designed.

At least high-level documentation that is kept up to date provides a much faster reference of the current status.

Reason 2: Technologies Change

When in the technical design stage of a project, solution architects will often have a pretty good idea of how the final product should look; however, in today’s world of agile development, the architecture and design will often be tweaked along the way. For example, new frameworks may be introduced, new APIs may be leveraged and these technology changes need to be captured and updated in the overall technical design documents.

Similar to reason 1, when a new teammate joins or an old teammate picks up the code that he hasn’t worked on in a year, this big picture view will help clarify the details efficiently.

Reason 3: Business Requirements Evolve

Properly documenting the use cases, user stories and requirements early on is key to gaining a common understanding of what the application will do. Keeping this information updated is also key in order to make sure it can be properly maintained over time.

As features get deprecated and new features get added, it’s important to keep a single source of truth for the application’s current standing.

Reason 4: Documentation Facilitates Discussion

Once a solution is written down, it can be easily discussed and distributed to get validation. Especially with forward thinking projects, it can be invaluable to get advice from a third party (whether internal or external). By having a clearly documented solution, even anonymized as needed, you can reach out to local experts and gain their feedback. This will help identify potential problem areas to ensure the most suitable solution is being proposed. We’ve been in situations where a client would like their software audited to see if it can handle a specific need – in projects where the software is properly documented it is much quicker to analyze its strengths and weaknesses. In a project where the solution is not documented, the first step will be to reverse engineer, then analyze.

Reason 5: Documentation has real value!

Documentation is a real asset that adds value to your software. If two companies were selling the exact same software (and everything else was relatively equal), the documented software would be much more valuable. Why? Because it would take significantly less time to get value from that software.

Your team can ramp up on documented software, understand the requirements, build on the technical design, identify and resolve issues quickly.

Pro tip: Documentation doesn’t mean MS Office, leverage existing systems

One subtle point is that documentation doesn’t have to be beautifully written, formatted, and printed MS Office documents.

The best documentation is automatically generated, maintained, and versioned through your existing project management, source control, and test case management tools. Use those tools as the single source of truth for the current standing of your application and you won’t be inefficiently spending time updating documents – also, you’ll reduce the risk of having outdated copies of documents.


0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *