It is not easy to prepare a good project specification document. Therefore, based on my experience, I prepared a short guide on how to avoid most common mistakes in the process of writing project specs. I hope it will help you to prepare a good specification document for your next software development project and then to choose the best offer, both in terms of business needs and budget.
Pitfall #1: project specifications are too general.
In practice, this means that expectations are not well defined and leave room for different interpretations. And depending on the interpretation chosen, the project budget and timeline may be estimated differently. Sometimes, such a difference can be considerable and has great impact on the final project cost.
A professional service provider, if there is no possibility of asking questions to clarify the requirements, will choose the interpretation that is the most probable based on their experience. Of course, despite the good will of the service provider, their interpretation may not reflect the intentions of the buyer, which will lead to problems during the execution of the project.
A good example of this pitfall from my experience was a requirement saying that a developed piece of custom software should allow users to generate reports based on data provided. The number, goal, and target audience of these reports was not specified. Additionally, there was no information on the data range required or on how it should be presented. Should it be a simple report? Or an interactive one with many customization options?
We could build the system with an extensive reporting module featuring built-in predefined reports and tools for end-user report design. We could also build the system with a single tabular report presenting all entered applications. Both would meet these requirements. However, the differences in the cost of delivering these functionalities are significant, just like the functionality for the end user.
How can you avoid a too general project specification?
For each requirement, if you don’t know the specific parameters, add a precise description of the context of this requirement addressing the following:
- Who will benefit from this requirement (or feature)?
- Who among the project stakeholders submitted such a requirement and for what purpose?
- What level of flexibility (that is configurability, individual adjustments, interactivity) does the user expect?
In this way, a reliable IT service provider will, based on their experience, be able to make the appropriate assumptions on how the final feature should look.
Pitfall #2: project specifications are excessively detailed.
Adding too many details to the project specification does not bring any additional value for estimating its scope, cost, and timeline. Of course, too many details are always better than too few, but they require extra effort both from the buyer and the IT service provider, and do not help in delivering the final product. So, the specification should be prepared by people with business and technical expertise and experience.
Moreover, there is usually a business analysis phase that aims to define these elements, so there is no need to go into too many details in the specification. Even more importantly, when focusing on secondary questions, it is all too easy to overlook key requirements and business goals.
I recall an illustrative example of this pitfall from a recent tender process we took part in.
The buyer provided a detailed description of the data model, constituting most of the order specification in terms of volume. This was unnecessary. It would have been enough to provide a description of the domain along with a rough estimate of its scope. However, the description of business processes (for example, in BPMN notation) was omitted. Such a description would have been less labor-intensive to prepare and would have contributed significantly to defining the solution and determining its complexity.
How do you avoid falling into this trap?
Strike a balance in the description of requirements based on their importance and complexity. More critical requirements should be described in greater detail, while less significant ones should be more concise. This approach will help you distribute emphasis appropriately, highlighting what is most crucial in the project. IT service providers will focus on the key aspects of the project. A requirements specification is not an academic essay. It does not need to be overly lengthy. An overly detailed specification will require more work from IT service providers and won’t have any positive impact on the quality of their offers.
Read more on bespoke software development:
Business process optimization in the pharmaceutical industry in 2024—7 practical use cases
How to choose a tech stack—10 factors every CTO/CIO should consider
Azure OpenAI services: potential business use cases
Is ChatGPT dreaming of conquering the world? Generative AI in business
The power of generative AI at your fingertips—Azure OpenAI Service
Business process optimization in the pharmaceutical industry—7 practical use cases
10 reasons you should consider legacy system modernization
Why build a custom e-commerce platform for B2B clients in the manufacturing industry?
How to choose an enterprise software development company—a checklist for CTOs
Pitfall #3: the specification is not complete.
This may lead to various consequences.
First, the buyer may accept an offer that conforms with the project requirements but does not align with the business goals of the solution. In this case, there will be two options. The buyer will need to increase the project budget during the procurement process or after its completion. Alternatively, they will need to accept a solution with limited functionality. Regardless of their choice, change management skills will be necessary to navigate through this situation.
Second, the buyer may get offers that can’t be compared because the IT service providers have focused on giving the lowest price, omitting requirements that were not described. Alternatively, the providers may have based their decisions on ensuring coherence and completeness of the solution, increasing the project cost and thereby diminishing their chances of winning the deal.
I recall a good project specification example with this pitfall. It was a specification of a business process automation solution for order processing. The buyer stated that the solution should use data retrieved from an ERP system (SAP in this case) imported during the solution’s deployment. From the IT service provider’s experience, it seemed unlikely that the buyer, during their activities, would not modify or supplement their range (that is, product base). At the same time, the expected solution did not include tools for modification after the initial import. So, in other words, once the data was imported into the solution upon its deployment, the specification did not describe how this data could be updated.
If an IT contractor had prepared a solution sticking literally to the requirements, it probably would not have met the buyer’s expectations or their business goal. On the other hand, a professional IT service provider would consider the scenario where the data needs to be updated after the deployment of the solution. Yet in this case, the project cost would probably be higher. This situation creates a vicious circle that is difficult to escape from.
How to avoid falling into this vicious circle?
The most important thing is to take your time when preparing a specification. You need to have enough time to verify it a couple of times. Best practice is to have the specification verified by different project stakeholders who will analyze it from different points of view. The more people look at it, the easier it is to spot potential gaps.
You can also add an extra step in your procurement process where IT service providers can raise their concerns or ask questions.
Pitfall #4: the project specification is not coherent and consistent.
The answer to why this is important is obvious: you cannot fulfill requirements that are contradictory. Some contradictions are easy to spot. Yet in some cases, project requirements may look consistent but lead to contradictory conclusions about how the project should be executed. This situation is more difficult to detect.
What will a reliable IT service provider do? They will raise this problem or ask questions. Alternatively, based on their experience, they will assume how the complete software solution should look, leaving out this contradictory requirement. If the contradictions are serious, an IT service provider may simply withdraw their offer.
I will give you an example of such a situation.
In a solution supporting the process of legal documentation preparation and acceptance, the buyer set a requirement that end-to-end encryption needed to be applied to the marked document sections. And this encryption needed to be implemented on the client side. At the same time, in another part of the specification, the buyer specified a requirement that the application needed to duplicate validation rules and apply them on both the client-side application and server services. This was impossible to achieve when this data was not present in an unencrypted form outside the client applications.
Another scenario involved the direct copying of generic requirements without adapting them to the project’s context.
How do you make sure that your specification does not contain contradictory requirements?
From my experience, I can say that this problem usually arises when different stakeholders contribute to the requirements. They may represent technical or business departments, or the final recipient of the solution (for example, a marketing or sales department). In both the above cases, the solution lay in a multi-faceted verification of the requirements. It is also important to work with a reliable IT services provider that will be able to spot such inconsistencies in time.
Pitfall #5: the specification is prepared by people with no technical background.
As a result, they cannot verify how requirements may affect project costs and timelines.
Why is it so important to avoid this mistake?
Because the business significance of a requirement is not directly correlated with the effort needed for its implementation. Seemingly minor changes can have a substantial impact on solution costs. If technical teams are not involved in preparing the specification on the buyer’s side, and the task is delegated to the business departments without thorough verification from a technical perspective, the offers received from IT service providers may come as a surprise.
Furthermore, if the components of the cost estimation are not described in a detailed way, the buyer cannot evaluate which requirements caused a significant cost increase and correlate them with the business significance of each requirement.
A good example that I often encounter is the approach to versioning changes in a system. If the business expectation for the system is to record information about who made a change when and with which version number, this is a requirement that does not significantly impact the project cost. However, formulating this requirement as “The system must version changes made on the form, so that the user can identify changes, their author, and the time of execution” suggests that the versioning should also include what values were changed. This also implies storing and visualizing all version information for the form. Such an understanding of the requirement is common, and it cannot be ruled out that the buyer did not interpret it this way.
When the IT service provider asks, the business user that created this requirement may confirm interest in full information (why not?). But they may not be aware of how this decision will impact the final project cost. The complexity of this option is incomparably greater than simply tracking version metrics.
How do you avoid such unnecessary costs?
When preparing the specification, it’s essential to involve people with experience in implementing solutions and assessing business requirements. If this is not possible, consider conducting a separate analysis before starting the project to identify and clarify requirements that need more effort to be fulfilled.
A less effective solution is to ask IT service providers to indicate the weight of each requirement in terms of the workload needed to realize it. Bear in mind, however, that there are requirements regarding shared system components that will have a common workload. To calculate the workload for each of them, you will need to divide the workload proportionally according to the number of the requirements. If the buyers resign from one requirement, you need to calculate the workload for the others afresh. So, all workload estimations will have only an indicative character.
Pitfall #6: requirements are very general and vague.
It is assumed that the knowledge and experience of an IT service provider in executing similar projects will enable them to submit a good offer. So, the project requirements do not need to be very specific.
Why is this a mistake?
Because, in the case of custom software, each organization and each implementation is unique. Even solutions of the same class implemented for clients in similar industries usually vary significantly in implementation costs. Specific requirements, which differ between clients, as well as the solution’s environment—its extent and level of integration with external systems, organizational structure, data migration scope, other performance-related requirements, and many more factors—impact these differences. Different IT service providers preparing an offer for you can assess the solution’s complexity differently, even based on similar implementations. This leads to difficulties in comparing different offers for the same solution.
A good example is a leave request processing application. This is subject to labor law regulations, so it has a well-defined logic. In its basic scope, it is also quite a simple application. However, the organization’s specific needs can result in a significant increase in complexity. These can include integration with the payroll system (importing employment parameters and leave balances, exporting leave statuses, retrieving data on entitlements and exemptions), integration with systems like Active Directory for importing user accounts and linking them to personnel data, retrieving and building the organizational structure to designate approvers, adding optional functionalities for leave planning, exporting user status outside the office, and many more. These requirements can vary greatly from one organization to another, causing substantial differences in the complexity of the solution.
How to make sure you get the good offer?
So, bear in mind that specifications should consider the unique characteristics of your organization and identify specific requirements. All doubts must be cleared up during the request for information phase and before the final price of the solution is given.
Pitfall #7: the specification lacks necessary information.
As a result, the requirements cannot be met.
How does this mistake look in practice?
Sometimes, it is expected that an IT service provider will supply a detailed description of a solution for a requirement that was not explicitly provided. This could include environmental scaling, specifications for required licenses, performance assumptions, et cetera. Providing these details in the solution proposal requires input data that is not always included in the specification. Determining the required disk space for a solution depends on factors such as data volume, data retention policies, backup policies, et cetera. On the other hand, calculating computational power is possible if the specification supplies the number of users and their work characteristics (for example, seasonal workload). Defining the environment’s topology, however, requires specifying expectations regarding solution availability. This is essential data needed to address the required issues. Without this data, it is not possible to prepare such a proposal.
One of the most common examples is a request to propose the physical architecture of a solution while omitting requirements related to system availability. The IT service provider cannot predict how critical the solution is to the client’s business and what the acceptable downtimes are without this data. And without such information, it is unclear whether to assume the redundancy for components in the physical environment, the standby mode in which backup nodes should operate, and so on.
How to avoid this mistake?
Therefore, when formulating project requirements, it is essential to thoroughly analyze what data may be necessary for the buyer to provide. The buyer should supply such data. Alternatively, the buyer should provide hypothetical data that can be used to compare different offers from IT service providers.
Pitfall #8: preparing specifications from existing materials.
These can be, for example, previous IT projects or corporate standards.
It is rare for an IT project specification to be created entirely from scratch. The reason for this may be simple pragmatism, where many elements of such a specification are repeated across other IT projects and can be reused. Sometimes, it is a deliberate approach, when general corporate policies and standards are attached to the IT project specification.
This mistake results from a lack of verification if the reused or attached documents are up to date and coherent with the rest of the specification. This leads to situations where an IT service provider encounters information that is contradictory. A reliable partner will either bring the problem to the attention of the buyer or assume that specific requirements have precedence over general ones.
An example could be a procurement department attaching the same technological standards without updates from the IT department. As a result, these standards impose the use of outdated software versions or technologies that are inadequate for the conditions of the specific IT project. Another example would be the previously mentioned requirement for server-side validation of data entered by the browser (included, for instance, as part of general application security requirements) in the specification of a system implementing end-to-end encryption.
How do you solve this potential problem?
When standard policies or repeatable fragments are included in the project specification document, you need to verify whether they are up to date and are consistent with the detailed requirements for this software solution. If such inconsistency exists, detailed requirements should be prioritized. Alternatively, contradictions should be resolved on a case-by-case basis.
Pitfall #9: incorporating general legal regulations into specifications.
And more specifically, incorporating legal regulations into specifications without ensuring they clearly describe the conditions of the buyer’s operations.
When building solutions that implement requirements that stem from legal regulations (for example, in the life science industry), buyers require that the solution is compliant with these regulations. This is easy to understand. In a highly regulated industry, compliance is of critical importance. But usually, legal acts are documents that have high universality that regulate the entire field of a given business activity. They can contain legally binding requirements that do not apply to this particular solution or additional criteria to fulfill if certain conditions are met. IT service providers may not be aware of such legal requirements.
A good example is the case of a project of designing and building a document management solution. In systems of this type, Polish law requires that the identifier on the shipment must be readable without the need for additional devices. If this requirement is met, additional machine-readable identifiers can also be placed. Thus, the legal regulation allows for some flexibility. But if this is incorporated as the part of the specification, it is not possible to determine what the precise requirements of the buyer are: whether it is enough to put just one identifier or two—a standard and a machine-readable one.
How to avoid this mistake?
So, remember that legal acts attached to project specifications should have a supplementary nature. The scope of the solution to be built should be described in the specification. Particular emphasis should be placed on issues not covered by legal norms or situations where different approaches are possible.
Pitfall #10: the license costs needed to be inluded in the offer.
More specifically, it is required to include in the business offer the license costs needed to run the software solution, but there is no differentiation between those provided by the buyer and those supplied by the IT service provider.
Why is it a mistake?
This pertains particularly to server software, which is often already owned by the buyer. Even if additional licenses are required, it is more advantageous for the buyer to buy them through their existing agreement rather than from the IT service providers. Additionally, different IT service providers may offer these licenses in various models, making it challenging to compare offers.
Here is an example of a project specification document with this pitfall.
The buyer specifies that the solution is to be built on the Microsoft technology stack and has a Microsoft Enterprise Agreement. Simultaneously, in the specification, they request details on the type, quantity, and cost of server licenses required for the solution. IT service providers are unaware of the buyer’s contract terms, and they may present prices that differ from Microsoft sales models, leading to imprecise information that varies between offers for reasons unrelated to the solution’s specifications.
How do you avoid this pitfall?
Best practice is not to require IT service providers to give information about license prices. Instead, specify the number of licenses needed. Also, you need to specify what server software is provided by the buyer and what by the IT service provider.
10 pitfalls to avoid when preparing an IT project specification—summary
As you can see, there are several traps you may fall into when preparing project specs for your next software development project. Therefore, this should be done carefully and with consultation of all potential stakeholders. All this to make sure that the final project specification example document gives precise requirements that align with the business goal of the project. I hope this short guide will help you to write project specifications that will translate into successful project execution and delivery.
