Most programmers can relate to staring at a text editor not sure what they want to build. Most engineers dream of taking something that already exists and building it again, but better this time. What happens if you don't have something to recreate?
Ultimately, most people quit their attempts to create something new, or they come up with requirements. These requirements may not be the requirements of the Waterfall era of project management, they may be flexible, they may be core reasons for your creation to exist, or they may be whims someone figured would look good to their peers.
The purpose of a requirement is to gain a shared understanding of what you want to build. They don't need to be complicated, but they need to exist. "When I sit down to work on X project, what am I trying to make X project do?"
It's very easy to stop writing requirements too early. If what you want can be satisfied by a REPL, then you need to clarify what you mean by letting "anybody" do "anything." If your requirements can be satisfied by a small set of functions, "I as a user want to square a number," will be satisfied relatively quickly. Then someone, the engineer or the user or someone, needs to come up with more requirements.
Now I may be turning people off with the word "requirements" and one of my implicit requirements for this post was not turning anybody away. Let's talk about other forms for expressing what must exist.
It's quite common to have a roadmap in a project. Given the passage of time, these are the features or abilities we will be building. These are, in their own sense, requirements. They can adjust, but they also give the developer and any third party who cares a chance to peek at the final form of the software.
Agile also has requirements. It calls them User Stories.
"I as a $purpose want to do $thing"
This is meant to contrast with classical requirements, and as such is a way to write requirements with a different mental focus. Instead of saying "The program needs to allow social auth" you write "I as an average human want to log in with my Google account." This suggests a whole different level of quality, testing, and conformance to the underlying requirement "social authentication." After all, if you are a user and you want to log in with Google, it had better be easy. Has someone tested to make sure it is easy? Has someone in management or a third developer tested the application and confirmed that the average human could perform the task?
User Stories, more importantly, give you an easy way to remove stories if they don't make sense. Do our users actually care if they can use Internet Explorer to view videos in our app, or can that story go away? This perhaps is the most powerful part of this approach to requirements. The framing of a user doing something helps transport readers, be they engineers or managers or executives, into the mindset necessary to make decisions about the requirements. Tell people that you need OIDC and their eyes glaze over. Tell people Sally who bikes twice a week just wants to log in with her Google account, and it makes sense.
User stories make sense when the user is the point of the application. What about times when that's not true? Before you get out your pitchforks, imagine most business to business software. "I as our business want to make sure our tools are all working correctly." Excellent story. You are proposing a monitoring soluton. Or are you? From the text of the requirement, a manager can assume "Oh so we'll have someone check on that stuff every so often." All that stuff about managers understanding the story? Gone. All that stuff about sharing mindsets? Gone.
What about an alternative, not to replace user Stories, but to fill a communications gap. Classical requirements are excellent for people used to working with requirements and the techniques/technologies involved. Roadmaps make excellent sense to people who are invested in the project. User stories are excellent when working on user facing program. Notice the trend? All of these speak a language the readers already know. User stories are for devs and their managers, and ideally for communication with the users. Roadmaps are for devs trying to either predict or help with the future of a project. It's hard to summarize who natively speaks classical requirements, but they exist.
Let me tell a story. #
There is an office of reliablity. Every hour on the hour, except lunch, someone from the office goes and loads every single one of the company's tools. Every load attempt is written down, with the time, a few feelings (was it fast? did it feel slow?) and some common uses are tested (Can we create a user? Does our record keeping allow file uploads?). These are written down and then they are published. Anybody in the organization can view the published results. The office of reliability is not responsible for telling anybody about the test results when there is a failure, not at this time. We are expecting someone from the office of operations to check the published results regularly, and leave the responsibility for fault remediation with that office.
I showed this story to a few managers. The first feedback I got was "There is no financial sense in having such an office." I agree. However the same manager would agree that the job function should exist, just not as its own office. Either that, or they would say the customer could serve as the hypothetical office of reliability, and just raise a support ticket when something broke.
Why do we write requirements? To communicate to others what needs to be created before we fully understand the resulting product. Nobody who reads the requirements for a tool can claim to be an expert in the tool. We also need to know that we could live with the result, whatever ends up being created. We communicate through requirements to ourselves, to others, and in corporate settings, to management. Management who can understand hiring someone to perform a task.
Software people see the "office of reliability" and immediately go "Oh, a monitoring system." Yes, a monitoring system.
The core idea is as follows: instead of expressing requirements as user stories, imagine that the world looks like Calvin's dad explains it in Calvin and Hobbes. Inside every ATM there is a little person who pushes the money out through the slot. Facebook is a dozen harried editors who frantically shove advertisements and some posts from your friends in your face when you ask. Status pages are updated by grouchy people who regularly check on all your services and confirm they are OK.
Let's describe a manufacturing ERP system. #
Not the whole thing, but just a tiny subset.
Office story:
The office of component tracking has a stack of files, one master file for each part in the system. These are cross-referenced with the type of part that's involved. When a change in part location is filed, the relevant file is located and the new location is written underneath the previous status. After that, the office confirms that the simple summary of the part has been updated to reflect the current whereabouts.
User story:
As a logistics expert, I wish to confirm whether the things I recently shipped are in transit or arrived.
Some requirements work great as user stories. In other cases, office stories let you fill in more of the bones of the need, helping everybody stay on the same page.
This is not confined to business software. You could write stories to describe the exact motion of, say, a motor controller trying to control a crane. Yes, if a human team were to be executing the story, they would need to be performing their tasks in microseconds or nanoseconds, but ignore that. Imagine your program as a tiny office, looking up the historical crane movements for similar situations, and ringing a big bell when those historical cranes have failed in their task. The office setting may not be appropriate however, and you may wish to imagine your people working a control room, or whatever setting is most appropriate to the tool at hand.
Here are some things to ignore when writing office stories: #
- The actor. The person who acts and triggers the office action should always be external. What matters isn't the actor, but the action they have taken. In this way, office stories and user stories do not overlap.
- The method of action. Yes our user could use a webpage. Or come talk to the office in person. Or file a form in triplicate. It doesn't matter to the office story.
- The timeframe. You can add time details (especially for periodic jobs) since they make a strong case for automating the job, but don't make them central to the story. Focus on the task, then argue for automation due to the time.
- Office motion. Paper moving isn't the task, it's a cost of humans doing the task. When we turn this into software, the database rows will stay in the database.
Here are some times that office stories are not a good fit: #
- Shared understanding. If you already share an understanding of what the program is supposed to do, in its particulars, then you shouldn't be writing requirements except to solidify that undertanding for your future self, or to regain unity if your shared understanding comes apart.
- No parallels. What you are doing is so new and outlandish that people can't imagine doing the work. You'll need different ways to describe your code.
- User centricity. If the office actions do not matter, then don't bother setting requirements on them.
- Non-collaborative environment. If you don't need to communicate to people who worked in a routine collaborative environment like an office, then the language of job descriptions and tasks might not make sense.
The office story highlights something important about the work we do as software engineers. We use software to make work that was previously uneconomical affordable and repeatable. Cars adjusting engine tunings while they run? It was more expensive to stop by a mechanic every 5 minutes and have them tune the engine to run right. Consensus algorithms? The communication to the villages of Paxos is cheaper and faster by computer. Software enables these office actions to be faster and more consistent. We should embrace that fact, and use office stories to share our vision for the future.