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:

1. Atomicity

2. Completeness

3. Brevity

4. Consistency

5. Feasibility

6. Prioritization

7. Testability

8. Unambiguity

9. 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.

Completeness

A requirement is complete if it contains all the information necessary to complete the task.

Brevity

The requirement is brief if it does not contain unnecessary information.

How to keep the requirement short:

1. Determine the main idea

2. 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:

1. Compare with other requirements. See if it contradicts what is already in the project. Perhaps related articles should be corrected.

2. Talk to the team. Discuss the new requirement, questions will show what to add

3. 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:

1. Budget. How much time does it take to implement it and does it fit into the budget?

2. Team qualification. Will the team be able to fulfill the requirement or do we need to hire new people?

3. 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