How detailed should requirements be?🤔
Tags: softwareengineering, requirements, communication, productowner
Published: 2023-05-25 11:19:41

I often get questions about how detailed I should be when communicating requirements to engineers, and how detailed it's common to be.
Let me summarize a bit.
This is written for those who communicate requirements.

---
## The objective is to get the expected deliverables

The purpose of communicating requirements to engineers is to ensure that they understand what needs to be done and that the expected deliverables are produced as a result.

Therefore, if the expected deliverable is not produced because the information was not included in the requirements, it is appropriate to consider this a failure on the part of the person who communicated the requirements.

It is important to start thinking from this point.
Blame yourself, not others.

You may be tempted to think, "Well, I didn't write that in the requirement, but isn't it **normal** to say..." 
(I am tempted to think that way in those situations, too 🫠)

However, it is easier to move on if you accept that the expected deliverables were not produced because you did not write something "**normal**".

## "Uncle in Tokyo"

![How many uncles are there in Tokyo?](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tyg2k332qwdbujd30i1r.png)


In everyday communication, when you talk to your relatives, you might say, "I met the uncle in Tokyo the other day" or when you talk to your colleagues at work, you might say, "My wife's mother's brother lives in Tokyo, and I met him the other day".

In everyday communication, we change the way we say things, thinking about how it will be understood by the other person.

In other words, "uncle in Tokyo" will be understood by some people,
But there are others who would not get the message unless you say, "My wife's mother's brother lives in Tokyo".

It is important to remember that the appropriate expression will vary depending on the person you are communicating with.

## Throwing Easy-to-Take balls

![Don't throw hard-to-get balls](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/37zcxkjtoykl4mz90spi.png)


If someone understands "uncle in Tokyo," there is no need to say, "My wife's mother's brother lives in Tokyo".

On the other hand, if you say, " Uncle in Tokyo" to someone who cannot be understood by "Uncle in Tokyo", of course they will not get the message.

It is the same when communicating requirements to engineers.
You need to determine what kind of expression is appropriate for **the** engineer to understand, and choose the appropriate expression.

## Conclusion

- The purpose of communicating requirements is to have them produce the expected results.
- If the requirements are not communicated appropriately, the expected deliverables will not be produced.
- To properly communicate requirements, appropriate expressions should be used.
- However, the appropriate expression varies depending on the recipient.

I believe that the first three things are important when communicating requirements.
In particular, I would like to emphasize that the appropriate expression varies depending on the recipient.

---
There are many ways and tools to efficiently express and communicate requirements, as well as related and indirect means of helping to communicate requirements, such as pair programming and code reviews. Many of them are also highly effective.

For example, when you are working with someone for the first time,
If you are unable to determine what is appropriate, a strategy might be to adopt an iterative development style to lower the cost of trial and error and then explore appropriate ways of communicating requirements.

You might also consider the ease of communicating requirements when building a team.

I will write about those in another article.

(Original Japanese ver.: https://note.com/akazah/n/n5706310d8ba0)