Design-Free requirements are important for two reasons, and hard for two other reasons.
Design-free requirements are hard because you “know what you want” when you should be documenting “why you want it.” Writing design-free requirements can be hard when you don’t trust your development team to “do the right thing” even though it is not your job to design the solution.
Design-Free Requirements – Revisiting
It has been three years since I wrote Writing Design-Free Requirements as part of The Big Ten Rules of Writing Requirements. In that time, agile development practices have moved from being an esoteric development methodology to being the topic on the tips of everyone’s tongues as executives and organizations try to either (1) get the benefits of the state of the art in software-development process or (2) do something shiny and fashionable.
The previous article centered on elements of designs within MRD, PRD, and SRS artifacts. A regular alphabet soup of artifacts. Honoring the values behind the agile manifesto encourages us to emphasize working software over comprehensive documentation. In that light, we’ll take a “what is needed” approach to talking about how requirements, design, and implementation are all needed – rather than issue an edict about where that information should be captured.
Agile Development Inputs
When creating software, someone needs to know:
- What problems are being solved, and how important (valuable) they are to be solved.
- Who has the problems and who is using the software to (help) solve those problems.
- What constraints limit the space that defines the universe of possible viable solutions.
- What acceptance criteria define if the delivered solution will be acceptable.
Subject to those inputs, someone needs to make design decisions:
- User experience design – what interactions will a user of our solution love?
- Program design – how (in a nuts and bolts way) will our solution function?
When talking about agile and talking about design, we should take a look at how Kent Beck and Alan Cooper, as respective though leaders in each space, view this.
Cooper doesn’t talk much about creating the requirements to support the daily use scenarios – he proposes moving directly into design of the solution. This differs from the more traditional technique of writing functional requirements to support use cases. Cooper also breaks down design into two components – program design and interaction design. Program design is everything you don’t see. Interaction design is everything you do see.
[…]
Cooper argues that designing the interaction should happen before any code is written. He uses a construction analogy to drive home his perspective – you can’t pour the concrete before you build the forms. Kent Beck, founder of the XP programming philosophy disagrees with the premise. Beck believes that the cost of changing software is low, and the imagery Cooper uses is hyperbole. We touch on, and link to that debate in this post.
I don’t believe that Beck is arguing for “don’t do design” – I believe he is arguing for “don’t do big upfront design that would delay implementation.” He’s championing the agile values that emphasize creating working software and responding to change. I can imagine him saying “no one will buy a design, they want a solution.” Cooper’s point is that create a solution without first understanding how someone will use it, you can’t create a great product.
Program design has many hidden impacts – cost of maintenance, cost to change, and the performance of the solution. You can have a design (or architecture) that makes everything easier to do in the future – at the cost of delaying the delivery of anything. Or you can have a design that minimizes the time to deliver the first thing, while increasing the cost to deliver any particular next thing. Or you can design a solution that falls somewhere between those extremes.
If you say “we don’t do design” you’re lying. Every solution includes design. Your team’s design process may be “big and upfront” or it could be a couple sketches on a whiteboard, or some email exchanges. You may create storyboards and wireframes. Or design may be the thing that happens right before the programmer’s fingers strike the keys. Design may be explicit or it may be implicit – but it never “doesn’t happen.”
In the movie Amadeus, Salieri is astounded that there are no rough drafts of Mozart’s compositions. That’s because Mozart did the design in his head, not because he didn’t do design. I’ve worked with programmers who’s “implicit designs” were great, but that is the exception, not the rule.
Who Owns Design?
Since design happens sometime before fingers strike the keyboard, the real question is – “who owns the design?”
- You have a product manager developing an understanding of market problems, and prioritizing the problems that should be solved with your product.
- You may have a product owner managing the backlog and clarifying those requirements (problems) for the development team.
- You may have an interface (or interaction) designer or team of designers who are broadly responsible for “how users interact with our products.”
- You may have an architect or lead engineer who is responsible for the “big picture design” of how your product works.
- You have developers and testers who are responsible for delivering your product. [Note: coding without testing is like typing code without compiling – maybe it works, but probably not.]
You may not have distinct individuals with each of these titles – every small team I’ve worked with has people wearing multiple hats. This is especially true when you have an agile team full of specializing generalists – any given story (or task) may have a different architect and different implementer. I’ve only worked with one company where the architects are NOT part of the development team. If your team is set up that way, please comment below – I had never seen that before, and I’m not convinced that it is the best way to organize – what have your experiences been?
Generally, “program design” is clearly owned by the development team – and product managers (and product owners) know better than to specify program design in their requirements. Neither the lead engineer nor the product manager believes that the product manager is a better programmer – so the product manager better not be specifying program design and mislabeling it as requirements. Coincidentally, Steve Johnson, at Pragmatic Marketing has a post running right now with a bit of a quiz – is this a req(uirment) or a spec (design)?
Where the line is more blurred is around interface and/or interaction design. Some development teams have interface designers as part of the team. Some companies organize with interface design as a “shared service” within the company. Either approach can be the “right one” – it depends on too many details to make a sweeping generalization. When the designers are members of the development team, the solution (from a product management perspective) is the same – the “team” is responsible for all design. When the designers are not part of the development team, the developers have to consume two sets of guidance – “solve this problem” from product management, and “the solution needs to look like / act like this” from the designers.
Collaboration between product management and user experience people is the ideal solution. The “requirements” and “design” inputs to the development team are comprehensive and consistent.
Design-Free Requirements
There are benefits – especially when being agile and minimizing documentation – to delivering requirements and design at the same time. Just don’t do it by embedding design constraints within the requirements.
- When people on your team misinterpret design as requirements, they are unnecessarily constrained.
- As a product manager – are you the best designer on your team? If you’re busy designing, who’s product managing?
This is trickiest when writing use cases – sequencing a set of interactions is interaction design. That is one benefit of writing a user story instead of a use case. An approach that has worked well for me with multiple teams is to deliver user stories (requirements) combined with storyboards (interaction design) and wireframes (interface design). When details are needed (usually when “changing” versus “creating” an interface), screenshots can replace wireframes. When business processes are complicated, process flows can replace storyboards.
Just don’t embed the designs within the requirements.
To me the most important thing is for the product manager/team to have a toolbelt with a broad range of tools and know how and when each tool is useful, and when its overkill.
Business analysts get stuck in trying to user every tool on every requirement which generates analysis paralysis. This also can sometimes create lower engagement from the engineers.
Plus – often people get all wrapped around the axel about the word ‘design’. Its all about intent and trust between the parties involved. A wireframe is a visual tool to help understand and convey a complex problem – it isn’t meant to convey interface design – unless that expectation has been set (formally or by accident). Again – use the right tools to solve the right problem.
Thanks Kevin (@kevind on Twitter)! Couldn’t agree more about remembering to be practical! Good point about wireframes as “efficient means of communication” versus “specified interface design.”
Working in technology, sometime – heck often times – requirements relate specifically to some technical capability that needs to be added in a product.
It could be specific API support or support for something like database stored procedures etc.
How do you recommend people create requirements for these kinds of technical capabilities, when fundamentally, there is significant cross over between the requirement and the spec?
Hey Saeed (@saeedwkhan on twitter), thanks – great questions.
I’ll start with database stored procedures. I’ve never had a requirement to implement a database stored procedure. I’ve had several requirements that a system provide responses (lookups / queries / whatever) in less than a specified amount of time (2 seconds, for example). I’ve worked on projects where the most reasonable way to implement that is with a stored procedure, but you could choose to implement by creating a view in the database, setting up a new database table to specifically respond to that query, etc.
Any of that “under the hood / how you choose to implement” stuff should stay that way. Requirements are explicitly outside-in perspectives on what your product needs to do, or how well it needs to do it. Calling out an implementation choice is an entirely inside-out mindset, and good requirements don’t include it.
API support is different. I prefer a user-centric approach to designing software, which is really to say – what are the interfaces, and what are the actors trying to accomplish? For a person, the interaction is created as a human-computer interface (HCI). Sometimes, the actor is another system, leading to a computer-computer interface. When building interfaces for humans, you have constraints (be in the local language, adopt a common/comfortable/consistent paradigm or metaphor, etc). When building interfaces to other computers, you similarly have constraints, non-functional requirements, and requirements.
You can define constraints that specify your API language – REST, JSON, javascript, whatever. You may also have semi-technological constraints (must support legacy API calls for 12 months, must conform to a particular EDI standard, etc.).
You can define non-functional requirements that affect how your API must function – asynchronously, with an acknowledgement in under 100 ms, with a maximum of 3 round trip calls (chattiness) to accomplish your goal, etc.
Then your requirements expressly are “what must be accomplished” not “how must it be accomplished.”
This is one area where I’ve seen user stories work well, even though it takes a small mental leap to put into a story format, since the actor is a system.
As a third party product data-management application, I need to provide new pricing data to the product-data-master on a weekly basis so that all of the pricing-data-consuming systems will have access to that data as soon as it is available, so that I can avoid having inconsistent pricing data throughout my ecosystem.
This story makes sense when there is a shared context (that product data is being mastered by a central repository from which other applications pull data, and that the system under development is the repository). If you were writing the story from the perspective of the product data-management application, the repository would be the actor, and it would look like:
As the product-data repository, I need to know at all times (typically weekly) when pricing data has been updated in the source system, so that I can provide consistent pricing data to all of my subscribing applications.
When you’re dealing with “across applications” requirements, but you are responsible for multiple applications that make up a solution, you have to take a step back and draw a new “system boundary.” As a “solution provider” you may be responsible for both the management of pricing data and the updates to other systems. In that case, your architect is responsible for defining how the different applications interoperate (creating a pub-sub decoupled service oriented architecture, or tight integration into a shared database or whatever). Those constraints affect how solutions in the “system of systems” requirements are implemented – but are not “in scope” for a single-system’s requirements.
Given that system context, it might look like this:
As a product manager, I need to update pricing data on a weekly basis for all of the applications in our ecosystem, so that our customers always see the same price at any point in time, regardless of the channel in which they are purchasing my products.
Does that help – or did the addition of the “system of systems” concept get in the way of a clear answer? The enterprise architecture scale projects I’ve worked on in the past struggle with this notion, as teams are often siloed, and subject matter experts often express their desires in application-centric or implementation-specific language – making it hard to do the abstraction. Context diagrams really help with this, by the way.
Then you
I’d deal with API support in exactly the same way I’d deal with other “feature” additions. What set of problems would an API solve, and what problems need to be avoided?
The user for an API is a programmer. In the context of your product, what problems is a programmer trying to solve? What probles is a programmer trying to avoid? Functionally, a programmer wiht skills X, Y, and Z is writing programs that extend or make use of your product. The problems in the context of this functional requirement might include:
1. Learnability – It takes too much time and effort to write a program the first time (or first few times).
2. Ease of Programming – It takes too long to write a program even after learning the API.
3. Performance – Programs of certain types take too long to perform their function.
4. Scope – Programs that have functionality X, Y, and Z face the challenges above.
It’s not easy to define all of the problems a programmer might face in extending or making use of your product. It is particularly challenging to define the scope of the programs the programmer might write. However, these are precisely the types of issues we should be considering before a desigener actually designs an API.
The requirements will not be the API itself, but the problems the API solves and avoids for the programmer and the users of the programs.
Thanks Roger (@rcauvin on twitter)!
I think you’ve mentioned it before, but I completely forgot about the programmers who write against the API as also being key stakeholders. I think they drive most of the non-functional requirements (like your examples) about the usability of the API. I would argue that the right prioritization approach is to combine both the programmer’s needs with the capabilities required by the applications that are being integrated, and the users of that application.
For example, if you are allowing other (other company’s) web sites to sell your products, and your API is designed to expose inventory / lead-time / availability information about your products, then you need to consider the API-programmers, the affiliated-companies, and the users of their sites.
Oh, I almost forgot. Great blog entry, Scott. It captures and addresses in one post almost all of the requirements issues the community has been debating for years.
Thanks! I have to admit, I’m getting much more positive engagement and feedback on this article than I expected. Makes the whole blogging thing worthwhile :).
I’m trying to find time to write my version of this, a theme that has been close to my heart for a long time. So many people misunderstand UML and use cases, that what I see when on contract now is a travesty of what should be there. When you create UML the way it was originally specified, it works. It does all of the things you say you want. I will just outline my approach rather than trying to comment on what has been said above.
1. Start with the project sponsor and get a clear description of the Mission Statement.
2. Model the Mission Statement as a domain diagram.
Note a domain diagram is NOT a class diagram despite the fact it uses the same symbology.
The domain diagram portrays the business objects that the business find important to this project.
Business objects are things that are stable within the business; they will be more stable than the business procedures that use them. They are well understood, and there are a lot of small associated rules that govern how they are used. These are called Business Rules. In the software, business rules are less likely to change than use cases.
Do NOT try to get this diagram right immediately. You need it to be right when it couples with use cases, NOT now.
3. Identify Use cases. Use the ‘One Verb – One Objective’ style spelt out as three or four word descriptions. Start with the ones that you can think of, within the scope of the Mission Statement. You might find a few more domain objects here. You might find a few extra use cases. Dont make this a big thing. NO QA needed. Use cases do one thing for one actor.
4. Divide the use cases into sets that are inter-dependant. These form an ‘Epic’ which you depict in a single diagram. Add appropriate actors to the diagrams.
5. Write down the non-functionals at about the same level. These can include screen requirements again as business rules. Yes Roger is right, for an API, the user is a programmer, but normally, the programmer from the other side of the API, NOT this teams programmers.
Do NOT mix the domain model with screen requirements. In the full system class model, these two design aspects MUST be separated by an application controller; initially at least, one application controller for each use case. Wire models, storyboards etc can be used, but remember this is NOT the screen design stage, it is establishing the screen requirements, probably as non-functional support requirements or non-functional business rules. When these initial ideas are being developed, there is time to discuss them in detail, possably as first cut code.
6. Continue with the use cases. Link them to relevant actors. We should also attach a ‘goal’ – what is it going to do for that actor.
7. Goals allow you to link use cases without ‘include/extends’ wars:
if the goal of A is perceived to be part of the Goal of B, then B includes A. B makes the decision about whether is should be run or NOT.
if the goal of A adds to the goal of B, then A extends B. A makes the decision about whether the goal should be extended or NOT.
The first two rules also make sense of the arrows: the guy at the tail must know what the guy at the pointed end is going to do. The reverse knowledge is NOT important, except for the fact that the extended use case must know that the guy at the tail end must be given an extension point.
if you get them wrong, it wont matter at this stage; just do it.
8. If you know them, write down the triggers and preconditions. NOT the blindingly obvious, such as ‘the user must be logged on’, but the specific such as ‘When a mortgage has been underwritten’; conditions that must light up selections on menus or on buttons even if this control has NOT yet been determined.
9. Write down the ‘post-condition’. The post condition identifies, how you know, by examining the system or its database, that the use case was successfully completed or successfully aborted. This is the documented acceptance test.
10. The post condition should include consideration for all the business rules from the Domain diagram. How? It doesn’t really matter. That is the benefit of ‘agile’. Walk through, write use case detail in steps, draw sequence diagrams, look at the code and add junit tests. There are a few constraints which are too detailed for this summary, but even if it is wrongly accepted, the user may work with the system and find the problem. If you want to be be more formal then do something more formal; there are plenty of choices.
11. The post condition should also include all the relevant non-functional support requirements, including the user interface.
12. Finally, decide what to do in a sprint (or itteration) An epic, part of an epic, a use case or part of a use case. The latter requires that you identify which post-conditions will be achieved.
This gives a ‘Design Free’ specification highly suitable for Agile environments. However, it carries the strength of using UML to avoid many of the silly and dangerous arguements that occur.
UML is far more precise than most people give it credit for, largely because few sites ever use it correctly. This, when combined with the freedom to use UML as a support and NOT a set of chains, is very powerful but very agile.
Gil
Sorry that this is so long, but I feel it is very relevant.
Gil
That exceeded the ‘Seven plus or Mins Two rule’ Sorry. This is what I boils down to in four sentences.
– To get a ‘design free’ set of requirements, you need to split your understanding of what the users want into:
What goals the actors want to achieve, – Use Cases, NOT necessarily the detail step by step.
What the business is about and how it will constrain these goals. – Domain Diagram containing the Business Rules (usually constraints).
Of course there are the ‘non-functionals’ as well
You also need to reconcile these, but how is NOT hugely significant. It is that sp-lit that wins the day.
Gil