How to write a good technical specification?
Hi, my name is Julia Novikova and I am a systems analyst. Today we will discuss requirements quality criteria and how to apply them
What will we talk about:
why it is important to follow quality criteria when writing requirements;
how to check whether a requirement is good or not using quality criteria;
how to fix the requirement
Who is this article for:
junior analysts will learn to write clear requirements;
middles will make sure that everything is done correctly;
Seniors can share their experiences in the comments, which will be useful for all grades
I've announced the organizational information, let's get to the point
Why follow quality criteria when writing requirements?
Quality criteria are principles that ensure that requirements are clear to everyone
Clear requirements will help create the product that the customer needs and reduce the chances of that terrible analytical error occurring when delivering a project, when the client says, “But we wanted it differently.”
Quality requirements characteristics:
Atomicity
Completeness
Brevity
Consistency
Feasibility
Prioritization
Testability
Unambiguity
Clarity
How to check a requirement?
Run it through each criterion and adjust if necessary.
Atomicity
A requirement is atomic if it cannot be decomposed without losing completeness.
Instructions
How to check a requirement for atomicity:
Read the requirement
If there are no lists, conditions or conjunctions in the text, we proceed to checking for completeness
If so, check the checklist below.
If the item is applicable, decompose the requirement and return to step 1
If a point is not applicable, skip it.
Check list:
Separated functional and non-functional requirements
Each function is described separately
The stages of the process are delineated
Requirements are clearly divided into areas of activity
Completeness
A requirement is complete if it contains all the information necessary to complete the task.
Instructions
Check the description. Make sure to consider all possible scenarios
For example, if you described the creation of a user, do not forget about editing and deletingEvaluate the detail. Read again and add to the requirement if any clarifying questions arise.
Explore boundary conditions
Eg,
numeric fields and strings. Specify a character limit
files. Set the size limit in MB for uploading
number of records per page to set up pagination
Define success criteria. Ensure clear and measurable acceptance criteria are specified.
There was a requirement: “The buyer quickly orders the goods.” Let's measure the speed in steps. It became: “The buyer orders the product in 3 clicks.” It's already betterAssess how new requirements will change the system and correct the documentation
Look at the requirements from a different angle: think over the interface and write requirements for the designer, create a user story, draw UML or BPMN diagrams
Brevity
The requirement is brief if it does not contain unnecessary information.
How to keep the requirement short:
Determine the main idea
Ask the question “Can it be removed without losing meaning?” to each word in the requirement. If yes, remove it
Consistency
A requirement is consistent if it does not conflict with other project requirements.
Pay close attention to the description of the database and mappings. There are often mistakes here
How to write a consistent requirement:
Compare with other requirements. See if it contradicts what is already in the project. Perhaps related articles should be corrected.
Talk to the team. Discuss the new requirement, questions will show what to add
Illustrate the requirement with an example and check whether it is similar to the expected result. Choose an example illustration depending on the situation, but here are the common options: layout, script, diagram or excel file
Feasibility
Rate the resources:
Budget. How much time does it take to implement it and does it fit into the budget?
Team qualification. Will the team be able to fulfill the requirement or do we need to hire new people?
Technologies. Is it possible to implement the requirement purely technically? Discuss with the team
Prioritization
Prioritization is possible if the requirement is atomic, complete and consistent. This point is especially useful when the product is developed in iterations
Example of prioritized requirements:
The application supports authorization via social networks (VK, Telegram)
The application supports two-factor authentication.
Testability
Write basic test cases for QA, even if the requirement is “clear how to check.” One successful case and 2-3 with an error will be enough. This will speed up the team’s immersion in the task and the creation of unit tests from the development side
Unambiguity and clarity
Clarify the requirement with the customer and discuss with the team. Make sure that the participants in the process understand the requirements in the same way. It is important to obtain written confirmation from the customer
That's all. Now the requirement is good, congratulations on completing this path 🙂
What rules do you use to write requirements? Share your experience in the comments
PS: in my telegram channel Sherlock in IT I share my opinion on technologies and useful tools for analysts. I will be glad to get to know each other better and discuss other topics