Client Through the Looking-Glass, or How Not to Devalue a Project by the Lack of Documentation

When during another meeting a customer has to remind the developer all over again about the need to not break anything, then perhaps it’s time to take a broader look at the project. In such cases, it would be logical to raise the issue of replacing this developer or find out the reasons for such situations, but in reality everything might be different.

Therefore, it may seem that instead of the customer, the project is managed by the developer. As if the client depends on them and at the same time pays for the development process. It turns out to be a situation with confused roles or “Client through the Looking-Glass.”

Why does this happen and how can it be fixed? Well, let’s figure it out.

“I Hope This Time Nothing Will Break”

The situation when the client continues to put expectations on the developer despite the incidents that arise, usually, occurs because of the following reasons:

• Perhaps the specialist has unique knowledge or skills that are difficult to replace, and the customer has to put up with the mistakes;
• Or, the project lacks documentation, which makes the task difficult for all participants to understand.

According to the standards of project management, in these cases, an analysis of the current state of the project would be carried out to identify the main problems. Development processes would also be reviewed, missing documentation would be compiled, and additional training for the team would be conducted. It would also be helpful to discuss expectations and requirements with the customer to ensure that all parties understand the goals and objectives of the project.

If the problems continue, despite all the efforts listed, then the question of changing a specific specialist or even the entire team would really be raised. Ultimately, a successful project requires the well-coordinated work of all participants and mutual understanding and trust.

But in fact, a project suffers from the lack of documentation because of the desire to save resources. Unfortunately, it is easy to fall into such a “looking-glass” if you reduce the time, effort, and resources spent on defining and documenting the requirements that a product must meet to achieve business goals. Usually, these requirements can be represented in a Scope of Work, Software Requirements Specification (SRS), and/or Product Specification (SPEC).

Without proper attention to these documents, the chances of the project to face many problems, such as miscommunication between all participants, missed deadlines, and budget overruns, increase. Therefore, let’s figure out the value of such documents and if they are even required on the project.

Is Documentation Worthless, or Is There More Than Meets the Eye?

Often, before the first releases of the product, documentation has no value. Compiling and supporting it takes time and resources, and all you can care about at the start is to make new features and launch the product as soon as possible – there is no time for documentation. However, later on down the line, more and more situations, when changing the product source code in one part leads to bugs in another, will arise.

This leads to the team spending more time on fixing those bugs and troubleshooting than on developing new features. In such conditions, it becomes obvious that the lack of documentation significantly slows down the development process and worsens the quality of the product. When the project reaches a certain level of complexity, documentation becomes an indispensable tool.

Scenario 1. A Software Component Should Be Changed, But Nothing’s Recorded How It Works

Suppose a component has been adjusted several times, but it was so long ago that it is difficult to remember the details. The developer examines the application code and tries to understand how the specified feature should work. Without documentation, they have to spend a lot of time studying the code in an attempt to understand its specifics.

As a result, the specialist begins to refine the component based on their personal conclusions. After conducting Smoke testing, the developer shares their results with the client for verification and confirmation. Without knowing all the subtleties, the customer quickly sees that everything works as required and therefore approves the release of the changes. At the same time, neither the developer nor the client themselves expects any errors to occur or that the changes made will affect other features related to this component.

But due to the lack of documentation, understanding of the interaction of product components, and integration testing, a bug occurs. Eventually, it will be possible to learn about this kind of errors only from users, when they notice and report them.

Downside:

The lack of documentation slows down the development process and increases the likelihood of errors. 

Scenario 2. A User Reported a Bug and Asks to Fix It

Let’s imagine a situation when a user discovered an error in the application and reported it through the customer support system. After receiving a bug notification and analyzing it, the client assigns a task to the developer to eliminate the identified problem and update the product.

The analysis can lead to the following conclusions:

• The system behavior is adequate

The developer begins to study the source code and finds out that the system behavior reported by the user is known and expected. There is a comment in the code that explains why the system works the way it does.

However, the user’s complaint cannot be ignored, as it will affect their satisfaction with the product. In this case, the developer and the customer decide to record the found “bug” as an “improvement.” This means that the behavior of the system will be changed in the future to better meet user expectations.

Thus, the client and the developer find themselves in the situation described in the first example, where it is necessary to make changes to the software component without having complete documentation.

• The bug is confirmed

The developer begins to study the code and asks for help from colleagues who are familiar with the features of the software component of interest. Meetings are held to discuss the possible causes and ways to correct the error.

As a result, the bug is acknowledged, and the developer begins to fix it. However, without complete documentation, the fixing process becomes difficult, as changes in one place cause unforeseen problems in other parts of the system. Thus, the team again comes back to Scenario 1, where the changes made can affect other related components, which requires additional testing and revision.

Downside:

Without complete documentation, the fixing process and/or improvement is difficult and requires additional revisions and discussions. 

Read Also Earned Value Management (EVM): How to Forecast Project Outcome and When Does EVM Help?

Scenario 3. The Number of Users Has Increased and Software Optimization Is Needed

Let’s imagine that more users have started using the app and the load has increased. The team decides to analyze the current performance of the system and make architectural changes to support further user growth. However, no one remembers all the details of the implementation of this feature, since the documentation is missing or outdated.

Without the necessary documentation about the component, it will not be possible to take into account all the features of the software. Thus, due to its absence, the testing process after architectural changes will be incomplete. As a result, some bugs will remain at the stage of releasing changes, which can also affect both the operation of the application and its performance.

Downside:

Without documentation, the software optimization process becomes more complex and risky, as developers do not have a full picture of how the system works. 

Read Also Code Rewrite vs Code Refactoring. Choosing the Best Code Transformation Tactics

What a Customer Should Know

Without documentation (Scope of Work, SRS , SPEC), a reliable source of information about the entire product that describes everything as a whole and each feature separately, the customer and the project team are forced to rely on their memory and on the product source code. Besides that, since only the developer understands the source code, they are the only one who is able to tell how exactly the product works. Therefore, it is this specialist who becomes the one on whom the product, user satisfaction, and customer well-being primarily depend. Thus, the customer becomes dependent on the developer who creates all the bugs that cause dissatisfaction among users and the client themselves.

One of the false steps that customers sometimes take when they find themselves in such a situation is to replace the developer. The client may have the impression that the current specialist does not have the necessary level of knowledge about the product or has lost the former enthusiasm. Therefore, they make the assumption that another professional will be able to change the software for the better and with fewer errors. Such a decision significantly aggravates the situation.

If the current developer has partial knowledge of the project and is familiar with the operation of the software components, then the new specialist will need time to learn its intricacies. They will rely only on what they see at the moment in the source code of the product.

In this case, the new specialist will have to spend several months studying the code and encountering new bugs until they reach the same level of knowledge about the product that the previous developer had. While the customer is patiently waiting for the day when the new specialist gains full product knowledge, the company risks losing app users and revenue.

It is vital to understand that the lack of high-quality documentation can not only exacerbate the current problem, but also create new ones. Documentation is an integral part of the entire process of product development and maintenance. It helps to avoid potential problems by providing clarity and understanding of all aspects of the project, which ultimately leads to a more stable and high-quality product.

When requirements and processes are not properly documented, it creates dependency on individual team members and leads to serious risks for the project. Therefore, documentation should be easily accessible and regularly updated.

Read Also The Intricate Art of Maximizing Value. How To Make Every Coin Spent Worth its Weight In Gold

Conclusions

Documentation has no value, it is priceless. It is part of the entire development process and is able to ensure the long life of your product. Without high-quality documentation, investing a significant amount in product development, conducting an expensive advertising campaign, and capturing a part of the market may not give the desired result due to the protracted development of new product features and fixes. By not changing your attitude to documentation, you lose user loyalty and put the project at significant risk.

If you are familiar with the above situations on your current project, perhaps it is not too late to start creating documentation?

Contact us, and we will be happy to develop the desired product, taking into account the creation of the necessary documentation for subsequent successful changes and improvements to your product.