Technical Requirements That Don’t Make Me Cry
An attempt to bridge the gap between business and software development
Introduction
When I took engineering graphics class at the uni, most of my classmates and I had huge problems with placing sizes on the drawing correctly. Correctly means convenient for machine operator who manufactures a product, e.g., for a turner or a miller. The reason was simple: we didn’t understand the technology, the way that stuff was produced. We were not aware of what types of cutters existed, how a cutter was fed, where on Earth a spindle resided. It would be very difficult, if possible, to manufacture a product with our drawings.
Technical requirements are a program code written in natural language
Program code is being written in programming languages nowadays, not in a natural ones. The only reason for that is that there is no compilator invented yet that understands natural language. But when it will be, the code it will compile should work. For it to work, as a necessary precondition is to realize what logical parts constitute a project and how they communicate with each other. By logical part I mean some higher-level concept like a service. In order for the new feature you add to work properly, you should understand what logical part the new behavior belongs to. In other words, one should realize what the project you are engaged in basically is. It’s just a common sense, after all. Every project and the services it is composed of haven’t appeared just by themselves. They resulted from a set of some business-rules and business-logic. These are a function domain, whose image is the program code. Basically, any software is a business-requirements document expressed in a programming language. And when setting off to write a new requirements document I would treat it as a program code.
Say, we have a Technical support service and Transaction processing service. Technical support is for changing payment settings. Transaction processing service consists of a web-application for payment processing and service that actually processes payments, some sort of a gateway. So Sales service can change the behavior of Transaction processing service. Web-application sends requests to the gateway. That’s it. It’s enough to get a basic understanding of how things work.
Software developer writes code in some context. We don’t like to switch them too often. It’s even more comfortable for us to write code that works cohesively, code that works close to each other. It’s just a common sense as well. Since the code is just a reflection, a bijection of technical requirements, it’s very convenient for me as a software developer when a requirements document follows the same heuristics that I do when writing code.
Example
Say, I need to automate a robot who can go to the grocery store and buy some bread. Just like in more low-level domain decomposition, the same metaphors still apply in the higher levels. I think about the services each logical part can provide using the same human metaphor. If this example seems too naive, too evident to express my point, you can think of your system as a business-capabilities set. Anyway, what capabilities would this robot have? What services can it provide? I came up to the following list:
- Puts some clothes on;
- finds a way to the grocery store;
- chooses some bread;
- buys it;
- comes back home.
So this could be the contents of the first higher-level system description. Or it could be an introduction to the first requirement document. So a developer can identify the following higher-level responsibilities, or business-capabilities:
- Capability to put on some clothes;
- route finding capability;
- bread choosing capability;
- financial calculations capability.
Then new requirements arrived. If robot chose to go to the Aldi, he should by Banana Bread. If he decided to go to Costco, then he should prefer Nature’s Own Butterbread Bread. How would that look in real life? I should identify what grocery store I find myself in (there was no such requirement earlier), and I should distinguish Banana Bread from Nature’s Own Butterbread Bread — there was no such requirement as well. These requirements sound logical and clear. They just reflect desirable robot’s behavior in already known context. So they are easy to internalize for a developer.
So, if I’d need to express my point in one sentence, it would be it: functionality that should work together should be described together. In my opinion, this is the only criteria for requirements document structure. Widely-used separation of functional requirements and interface requirements is no more logical than using the criteria of parity of letter “z” number in a sentence.
Technical requirements should answer “what”, not “how”
A company’s CEO expects its developers to write a code that implements specific business-logic, that makes some money. The word “business-logic” contains the word “logic”. It’s not strictly defined sequence of actions, since there are usually multiple ways to achieve a certain result. It’s more like a set of delarative concepts of how the system should behave in any given situation. My CEO doesn’t care how I implement this behavior. What the system does — that’s what matters. So I need to know the answer to “what”, I can’t answer it myself. But the “how” part is exclusively mine.
Summing it up
For me, ideal technical requirements represent decomposed problem space without solution scent.
