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.

Importance of the Discovery Phase

Once you have decided to develop a mobile app, it is tempting to jump right in to development. But rushing to development is not the smartest way to build an app.

Beginning development with a discovery phase has lots of benefits that will better prepare you for the process and make it more likely to build a successful app under budget.

What is the Discovery Phase?

The discovery phase is where we work with you so that we both have a clear idea of the project scope and deliverables. We spend a lot of time understanding your needs and defining specific deliverables that will facilitate development in future project sprints. The discovery phase is normally charged on a fixed price basis typically representing 10-20 % of the overall projects cost.

Discovery Phase Deliverables

At the end of the discovery phase, you get documents detailing how to develop the application. These documents are the your property and they can be used to continue the development process with us or any other developer.

The discovery phase deliverables include:

  •  A requirements document including user stories, non-functional requirements and workflows.
  • A test plan.
  • A detailed project plan.
  • Wireframes.
  • Final UI.
  • Technical architecture and design like API specifications, necessary system integrations and security requirements.

Why is a Discovery Phase so important?

The main goal of this discovery phase is to completely understand the application including its overall goals and possible limitations.

It gives you a clearer idea of the scope of the project, the risks involved and the likely cost. It also helps smooth development.

Why is it good for customers?

By going through a discovery phase you get professional quality documentation that is used to guide development. You also get a more accurate estimate which will give you a clearer idea about your project, the scope, the platforms you want to use and the timelines that you are thinking about.

If you have any questions about our process or any questions about how we can help you in mobile application development including the discovery phase please contact us and take advantage of our 1-hour free consultation.