The word engineering can be scary, but in times with so many resources generating and speeding up the implementation of the solutions for us, the next bottom level for us, conscient beings, come to be the engineers behind the automation.
The better we're capable of expressing our desires and explaining our solutions, the more efficient we'll become at the execution level. The human factor is again the bottleneck.
Engineering the requirements shouldn't be hard, even when our clients don't know what they want. With this article, I would like to share some mindsets and tricks that I follow to raise a good level of requirements for simple and complex software applications.
What makes good requirements
Requirements are just translations of wishes or problems into visual and structured communication. This visual communication can be written or as simple as a picture or a diagram.
To simplify what makes a good requirement, I could enumerate the following:
Easy to read and understand
It doesn't matter how knowledgeable or experienced you are. If the others can't follow your mind, the requirements are as good as nothing.
A good requirement is not about how fancy you can sound, or how technical you can be, writing on your own cryptography of acronyms and terms that only you are familiar with. Sometimes other people should even be aware of the context in which you are writing the specifications, but in reality, there is always someone who's outside of the bubble. Writing requirements that can be easily understood by both the ones familiar and unfamiliar with the topic is what will tell whether the requirement description has a good quality or not.
Simplifying requirements is also a way of telling whether you, the writer, comprehend what you are talking about. In case you can't make it sound simple, maybe you've got some homework to do.
Now it makes sense to see why the adoption of standards is so beneficial for requirements. Standards are supposed to simplify the way the information is written and read. If so far you've been adopting or following standards just to look more professional, even though the standard is making the information look more complicated, you should rethink those standards...
Avoid untold expectations
Good requirements can convert any wish or need into a written sentence or draw a picture. It doesn't matter how obvious or redundant the information might sound, it should be explicit.
Remember, what is going inside your head is not always the same that passes in the head of someone else across the room. Let aside assuming that people who work in different areas or departments see things the same way.
If it is so obvious to you, it shouldn't be too painful to leave it explicit for everyone.
I remember reading in a book about how to improve communication, that a good way to have clear communication is to repeat what you understood from somebody or ask them to explain what have they understood from what you have said. You'd be surprised by how words can be twisted between a transmitter and a recipient.
Speaking of stating the obvious, good requirements are also good at pointing out what should not be done. A clear boundary limiting the scope of that requirement is what defines feasibility and helps to make that requirement estimable.
Input vs Output
From a systemic perspective, it all depends on giving input and receiving (expecting) an output. Some people refer to this concept as a "Black Box".
We can replicate this mindset on different levels: A function, a class, a module, a form, a system, or an enterprise. It should always be possible to identify what is the input, and what is the wanted output.
It means that the main pieces of information to be clarified during the requirements phase are how should the input look like, and what is the expectation toward the output in return.
Requirements should not be focusing too much on anything in between. Questions like how the system should be implemented should sit on the other side of the court, the solution field. Thinking that way, separate what is part of the problem and what is part of the solution. It helps us to break big topics into smaller parts, therefore simplifying them. By doing it, we decrease the risk of turning a solution into a problem or allowing a solution to be held back by a problem.
I considered writing about the "3 Ws: Who, What, and Why", but I don't want to mix too many topics at once. Feel free to look it up, though.
What I would like to focus on in this part is that requirements should be reduced mostly to telling what is supposed to be given and received, and by who. The question "why" should help on defining the value of the requirement and its priority. Everything else is probably sitting in the field of solution design, and should not be mixed with the requirement engineering, separating concerns, and decreasing the size of the problems.
Ok, I don't want to sail too far away from the subject, but I need to make sure I don't get misinterpreted. I do believe that the people who provide the solution should be the same people gathering the requirements. At least the same team. A cross-functional team. Anything other than that would be "too waterfall" compared to Agile software development. When people in a department gather the requirements for another department to work on a solution, communication issues happen very often. Let aside when a department designs a solution that another department or team will be working on. It just doesn't work that way.
To summarize, separate requirement engineering from solution design, and during the requirement engineering, focus on inputs and outputs following the 3Ws concept.
Data constraints and metadata
The main objective of the requirements should be on identifying expected behaviors for the software. I prefer not to skip the identification of use cases, examples, events, or behavior. Neither to invert the order between identifying behavior and identifying data.
Please, this is important. If you focus too much on data before you understand the business case, you will end up becoming a hostage of under-engineered driven solutions and trapped in invaluable meaningless discussions, like asking the customer "what fields would they like to have in the database table."
Once we have that covered, it is finally time to talk about data.
I see data as the substance matter of information that composes either an input or an output. Provided the business behind the requirement is already clear and understood, we should be able to clump data into the contexts it belongs, like this is user information, that is product catalog, etc.
But if you isolate one unit of data, you should need a little more information to describe it, beyond its keyword, of course. This is what can be called the data constraint. The constraint of certain data tells what are its boundaries. It is an email, but how many emails like that can exist in that given context? It is a file, but what are the extensions allowed for that file and what is the maximum storage it should occupy?
Data constraints can include factors such as limited storage capacity, restricted access to certain types of data, and compliance requirements that limit the use of certain types of data. These constraints impact directly the amount of effort necessary to have the data accepted and used within the system.
But how can we measure and keep track of what these constraints are, and whether they are being respected?
This is where metadata comes in handy.
Metadata is nothing but data for data. It provides information about the characteristics of the subject that holds the data. An email, for example, is data. But look what composes an email address:
The username, whether it contains a separator (@) or not, and the domain name, are all telling information about the data, regardless of who it belongs to or what is it going to be used for. Both "inform@gmail.com" and "inform@hotmail.com" are valid examples of email, but their metadata are different.
Raising requirements of data over data, or metadata, is what I consider a practice that takes requirement engineering to a next level of preparation. Given you don't need to know too much context for such fields, and they tend to repeat a lot, we can keep a quick checklist for them, and use them always when suitable.
In case there is no need to worry about such a level of detail, good. In case people haven't decided yet, assumptions can be made, and the best part is when no one thought about it, and that was the one requirement that would have become a blocker during the implementation if no one had asked about it.
Here is a list of metadata that can be raised during requirement engineering, from the top of my head:
For any type:
Creation or modification date.
Mandatory or optional.
Unique or allows duplicates.
Writable by any given role.
Any type of text, from a username to a long text:
Minimum and maximum length.
Text encoding: does it need to accept special characters or different alphabets like Arabic or Chinese?
Allows profanity or not.
Should be translatable or not.
Should be secure (XSS attacks)?
Should be encrypted?
Numbers:
Minimum and max values.
In the case of fractions, how many decimals?
Any specific unit, like speed, weight, Kilowatt/hour, percentage, or money?
Negative value allowed or not.
Dates or Date and Time:
Minimum and maximum dates.
Only past or future dates allowed?
Date format.
Is timezone considered, like ISO or UTC?
Ranges of any type:
Start and end entries can be equal?
Start and end combinations should be unique or allow duplicates.
Can be inverted.
Can interpolate.
Can be contained inside another range.
Can contain another range.
Files:
Minimum and maximum size.
Minimum and maximum number of lines.
Extensions allowed.
Specific file headers, which by the way contain exactly the file metadata.
Lists or enumerations of any type:
Allows multiple values selected?
Accepts custom inputs?
Should be made of key-value pairs?
Responses:
Maximum content size.
Maximum response time.
Output formats, like text, JSON or XML.
Minified or with indentation.
Compressed? If yes, which compression?
Be careful not to get lost in these terms. What I mean by data constraint is what needs to be considered for the input in an interaction with a system. Requests, responses, files, photos, or media, all rely on metadata as well. The ones I mentioned are some examples of data over data. Some of them are metadata within another context, and they can be part of your requirements or not. It depends on how technical it can be. My suggestion is to avoid too technical requirements. It should be inciteful for all the business layers to understand.
You can apply this concept in your own context, based on empirical knowledge across your career. Did you have to gather information about an address once? Save the questions you could have made against it. Street, number, zip code, country. All those carry their characteristics, and they can be the right question at the right time that will avoid lots of headaches during the development.
Answer your questions by yourself first
To wrap up, no, I don't think you should be making all these questions to your customer or your stakeholders right away. Or ask them to explain things again but in a simpler way. They probably never thought about it before.
My suggestion is for you to first raise the question to yourself or to your team, and most of the time, the context itself will provide you with a satisfactory answer. The answers you can't find with confidence, you can adopt assumptions and validate them.
Yet, for the things that seem to be too obvious or irrelevant, at least you now have them tracked, clearly stated, and aware by the people involved.
I hope these hints help you on your journey to better requirement engineering.
Cheers.