How to put comprehensive documentation together to achieve alignment in expectations?

Clients approach software development companies with particular requests for systems or products to fulfill their specific needs. When a chosen service provider takes the request “as is” and starts putting the documentation together, without verifying the validity of such a product idea, it may lead to misalignment in expectations and disappointment in the final result. I argue that the MVP approach is suitable even when the company is looking to develop a product for internal enterprise use, not to mention bringing a new product to the market.

I’m not a novice to custom software development and have been in a many of roles, from software development and product management to executive positions in IT. In custom software development, many times I’ve seen MVPs that don’t match clients’ expectations. Still more puzzling since product teams gather full requirements carry out analysis, produce thorough mockups designed. Where does the problem lay, who’s responsible and how to mitigate risks to avoid such an outcome? I’d like to make a point about how custom software development can use agile/lean practices to deliver viable products fast.

Let’s recall what an MVP is

Frank Robinson coined the term, which consequently was popularized by Eric Ries and Steve Blank.

“A minimum viable product (MVP) is a product with just enough features to satisfy early customers and provide feedback for future product development. Gathering insights from an MVP is often less expensive than developing a product with more features, which increases costs and risk if the product fails, for example, due to incorrect assumptions. It may also involve carrying out market analysis beforehand. An MVP can be part of a strategy and process directed toward making and selling a product to customers. It is a core artifact in an iterative process of idea generation, prototyping, presentation, data collection, analysis, and learning. One seeks to minimize the total time spent on an iteration. The process is iterated until a desirable product/market fit is obtained, or until the product is deemed non-viable.”

How does one determine if the MVP has been successful? The MVP is to test whether the hypothesis has been proved true or falls, ultimately providing the learning and information needed to continue product developing or stopping altogether.

What is an MVP hypothesis? And how do you know if it has been verified? In simple terms, to express a business hypothesis means to describe the customer segment, the problem they face, what the proposed solution to that problem is, and provide indicators that will allow gauging whether the hypothesis is true or not.

A quick note regarding the timeframes.

There is a misconception that an MVP must be done within 1-2 iterations, which is 2-4 weeks. And anything that falls beyond this timeframe is NOT an MVP. Whilst the point of an MVP is to test the hypothesis as quickly as possible with a minimum effort, the length of time it takes is not what defines it. It would be somewhat laughable to argue that an MVP is to be covered by a specific budget, wouldn’t it?

Note: It took us 4 months to develop the MVP of this product. Even though it took longer than “average” the product is showing a steady adoption by the users since it was launched (we know it because we have been tracing the metrics) and the investors provided funds for further development.

It’s important to note that an MVP is the first step towards the vision of the product that the provider of software development services helps the client to shape. The product may have a multitude of users in the future but at the start, the early adopters are to be targeted with the MVP. They are loyal and accept early releases with minimal functions, and at times, architecture that is far from ideal. They are prepared to provide valuable feedback and are eager to be the first ones to use the product.

A typical mistake is adding and developing functionality for every type of potential users. Economically, it wouldn’t make any sense to do so since we do not know which functions users will need and indeed use. Customer development methodology helps to shape the list of functionality and product features that will bring improvement to the bottom line.

Example

Let’s look at a hypothetical situation that unfortunately happens all too often in custom software development in Russia. With this example, I’d like to illustrate

What typical mistakes I still see people do when developing an MVP. What role hypothesis, metrics, and user stories play in expressing the MVP.

Here it comes

Ivan is the head of a small company that specializes in custom software development. His teams are fully staffed and pose all the competencies to carry out a software development project.

Oleg works for a medium-sized data-centric company that successfully launches products in its niche through well-tuned sales channels. The company employs experienced Technical Leads and Product Managers responsible for developing and managing the products. They sometimes outsource new product development.

The need for a new product has occurred. This service, monitoring system, was meant for internal company use. However, the experienced managers knew they could push it to the market and monetize it. Oleg went through the process of putting and defending a budget for the product development, got the money and signed the contract with Ivan. In this article, I briefly touched upon how to choose a supplier and what to look out for in a software development service provider.

Now, to make my point, below I describe two approaches that may take place when working on a product. I’d like to draw the reader’s attention to the execution of the User Stories and the value of the final solution.

Approach #1

“Classic” business and system analysts established how Oleg viewed the realization of the functionality with the help of an interview and draw a list of system requirements. They were asking the questions that sounded something like this:

How do you think the system should be realized?

In your opinion, what this functionality should look like?

How they went about documentation

Also, they described the various systems deployed by the client, and using the information obtained during the requirements elicitation session, they put a Technical Specification Document. The document included the following sections: the list of devices and protocols to be integrated with the system; the exact number of devices in each data center; non-functional requirements and functional requirements of the MVP expressed as user stories. The user stories were expressed as follows (the scope of the requirements was much greater but I will focus on a small scope this article):

As an Administrator, I can download a chatbot through my mobile messenger. As an Administrator, I want to receive timely alerts from the chatbot in case a critical incident occurs at the parts of the system I’m responsible for. (The definition and characteristics of a critical incident are provided as well. For example, the server’s CPU is working at 100% utilization for a certain period) As an Administrator, I want to be able to send the following commands to the system to address the critical incident, such as ‘Stop’, ‘Start’, ‘Restart’, ‘Reload’, etc) As an Administrator, I want to be able to request the system to provide access to the consolidated information in graphic form, to be able to assess many indicators and make an informed decision (Indicators that could be displayed in graphic form in a web- or mobile application were also listed) As a System, I need to integrate with the Zabbix server to identify its configuration. As a System, I need to interact with Zabbix agents to collect information about the applications. As a Senior Administrator, I want to see activities of all the administrators and see active incidents. As a Senior Administrator, I want to have access to and see the history of actions of each Administrator.

In addition to the functional requirements, Oleg wanted to have a sleek user interface.

The designers visualized what the communication with the chatbot will look like, added graphs showing required technical metrics of the system, created lists with filters to filter administrators and their activity history. The overall system logic looked as follows:

Ivan decomposed requirements, calculated the risks and send the cost estimate of the MVP development to the client. It turned out that Oleg did not have that amount of money since his budget had been approved prior to him finding out the costs.

In an attempt to reduce the development cost, Ivan and Oleg began reducing the functionality. However, after they removed a few features, Oleg was reluctant to reduce it any further. He started insisting on a discount claiming that other companies were willing to provide a better price and appealing to the long-lasting working relationship with Ivan alluding to the potential business together in the future. Ivan checked in with the analytical data and design mockups. He couldn’t see a way around reducing the functionality further, neither he wanted to ruin the partnership that was bringing a steady flow of contracts.

So the development of an MVP began. Whilst the programmers were writing code, a few user scenarios surfaced. The software testers found a couple more. Oleg introduced some changes also. Once deployed, the system started collecting data. It became apparent that the number of scenarios and the system design had to be corrected. Although the system was working, it was not entirely what Oleg was expecting.

Outcomes

Ivan evaluated his costs and it was obvious that due to the reduced marginality of the project, additional work and corrections he was at a loss. He didn’t feel that change requests would have helped the situation as he was aware of Oleg’s budget and it was a fixed-price contract. There was simply no room for change requests.

Oleg initiated a pilot with the system MVP within the company and was collecting the feedback from the users. It was hard to tell whether the MVP was successful. The subjective opinions and general feedback was not sufficient to determine the success of the MVP. It was also hard to make informed decisions about how to market the solution effectively to potential buyers. All in all, no one had the valuable knowledge to make an informed decision about the further development of the product: persevere or pivot.

Ivan lost money on the contract and didn’t even get a share in the venture. Ivan will likely refuse to continue to work with Oleg after all. And Oleg will have to find a new development team, practically starting all over with them by briefing them on the project, building new working relationships and effective dialog, all of which takes time, thus costs money. This is a no-win situation that leaves both parties dissatisfied.

Approach #2

In this case, Ivan’s analytics employed a product-oriented approach and did the following:

– clarified who the potential stakeholders and users of the system were;

– created user personas, identified their goals and motivation in using the system;

– described the main and supporting business processes that the user base was operating within;

– held a series of interviews.

They asked all the stakeholders questions, such as:

Why do you need this system?

What goals are you trying to achieve with the help of the system?

What tasks should it perform?

Who will use this system?

What are the competitors in the market?

What will happen if you never develop this system?

Imagine that you are using the system. How would you know if it has been implemented successfully? How would you know if it was unsuccessful?

At times, it was hard to interpret the answers: “Well, I need the system to provide better control over the staff and see the closed incidents reports”. Then the analytics had to use 5-Why technique to get to the bottom of things. “Why do you need to see the staff reports and control them? What will happen if you do not do that?”

The potential user interviews were based around the following questions:

How do you perform your tasks when situation X occurs?

How do you go about solving the problem X now?

Have you tried solving this problem differently?

In your opinion, how this functionality should be realized?

What value do you hope you will get with the help of the system?

What harm could this system do?

The analytics were interviewing until they had clear goals, metrics and had enough information to describe the solution in the following format.

For Administrators and their Managers of a medium-sized data-centric business with equipment distributed in various locations

who spent a lot of time to forсast and eliminate equipment failure because they are either away from their workstation or unfamiliar with the particular part of the equipment (in case its an administrator on duty) the mobile interface is a will provide quick access to the information and control functions of the equipment that is under the risk of falling or has failed that reduces the average time of incident resolution and the frequency of critical incidents due to the proactive approach in how incidents are handled, and consequently improves the customer loyalty toward the company products Unlike solutions X, Y, Z this mobile interface will have features A, B, C Leading indicators the average time from the moment an incident occurs until the Administrator starts resolving the incident

the average time administrator spends resolving an incident

the number of critical incidents a month NFR (non-functional requirements) The system is to process X GB per secondetc.

Sometimes even an in-depth interview is not enough to fill out the template shown above. To get a better understanding of what it takes you can read the Epic article at the Scaled Agile Framework website.

Having filled out the MVP-template as shown above, they have pulled together the user personas, leading indicators that the new system will impact, and the processes the users employ to fulfill their jobs. This has produced the following user story map. The user story map opens in a new window.

Beneath each blue block that contains leading indicators, there is a yellow block that contains a process within which the users work. Below, there are minimal solutions that can impact each indicator within this process. They draw a line under the user stories at the very top, thus delineating the MVP. At the same time, the number of user stories in the MVP, that impact leading indicators, can be added or reduced.

Outcomes

The starting point for the MVP in this scenario was the objectives and product metrics. The product decomposition illustrates how the goals lead the choices for the minimum viable product.

In comparison to the MVP developed in the first scenario, the results now are somewhat different. For example, chatbot functionality isn’t fully implemented. There is endless scope for improvement of the product in every branch of the decomposition. It’s clear how each user story informs and impacts the development of the product.

Had Ivan and Oleg had such a decomposition based on the goals and metrics of the MVP, they would have had a mutual understanding of what functionality to develop. For example, the functionality enabling control over the administrators, even though Oleg had a vested interest in it as he was effectively the Senior Administrator, was not paramount at that point. The reason being a lack of understanding of how monitoring of administrators would be carried out in the first place. All the more important, the goal was not to control Administrators but to improve certain indicators, meaning the functionality should have been different altogether.

The decomposition allows determining the set of functionality within the MVP and making sure it falls within the available budget. This will help to ship a working version of the system faster and filling it with actual user data. Consequently, this will aid in noticing and fixing unexpected scenarios as early as possible, which would be much more expensive to fix at the later stages.

In conclusion

Over the years in custom software and product development, I’ve concluded that a thorough Technical Specification Document on its own does not guarantee transparency of the expectations the client has toward the product. Results of the development process based solely on documentation may be rather disappointing. It is hard to fully describe expectations. One can only attempt capturing the idea of what a client anticipates to receive. All the finest details will become apparent only when a working version of a product or service is deployed.

Some powerful techniques and methods allow for achieving positive results. For example, instead of User Story Mapping, one can use Impact Mapping. Or, in the case of development of a product for internal company use, Total Value Opportunity can help to determine additional metrics.

I am convinced that in order for teams to work autonomously delivering high quality and speed, methods mentioned above and other Agile practices should be employed systematically across all teams in a development company.

Afterword

This article is based on my professional experience and what I’ve had come across in custom software development in Russia. I also reached out to the professional communities and asked a question of whether others had faced a situation similar to the one I have described above. I’d like to express thanks to all the people who responded to my inquiries, provided answered and shared their experiences and opinions.I confirmed that situations, whereby documentation is used as a sole source of information about clients’ expectations, are not rare at all.

Some respondents said that if such a situation had occurred then it is the analytics who was to blame and those responsible for documentation.

Others said that to avoid such a situation an Agile approach should be used. Some emphasized that documentation should not be regarded as the main instrument in communicating requirements, decisions, and artifacts. They also suggested that a version of the product must be deployed to validate the results, learn and document something that is of value whilst UX/UI design and the rest can hold on till later stages. All of the answers certainly gave food for thought and aided in writing this article.

Disclaimer 1: I’m not talking about a magic wand type of approach here, just trying to illustrate that it is possible to save time and money by avoiding certain mistakes.

Disclaimer 2: All characters appearing in the article are fictitious. The situation presented in the article is hypothetical. I intentionally omitted a range of details to convey the main idea and to keep the article as concise as possible. Please do not judge harshly.