I have experience working with web/app teams and building requirements for them. I'm now working with an api team and wanted to know the best format for communicating requirements. I've tried high level "endpoints" with descriptions, but it seems a little too high level. I also don't want to dictate implementation or design of the requirements (how the team fulfills the requirements). Any ideas?
4 Answers
You can choose to go one of two ways.
- Detailed, up front requirements. Very precise, not flexible and required a lot of up-front work.
- Goal based "Stories" that describe what the end user experience should be like. Remember the end user does not have to be the guy on the street. It's who will be using it day to day. Doesn't require a lot of up-front documentation, does require being available to the teams to answer questions. Allows the team to decide on "How" they will implement the "What".
I'm, of course, a big proponent of #2. I was a product manager in the 90's and co-wrote a #1 style document. We put a line in the middle of the document that said "This is a pink elephant. If you read this, we'll pay you $20". We never paid anyone.
However, as you have already noted, option #2 can be equally difficult as you struggle with "How much is just enough, so I get what I really want."
The secret to this is Acceptance Criteria. When you give a user story, you need to give testable acceptance criteria to the team. I like to describe these are "Gaurd Rails" for development. As long as the team stays inside them, they can do what they want. Acceptance Criteria should be "Yes/No" answerable. "Is fast" is not a good AC. "Is 10% faster over the previous release" is good as you can test it.
You also need a strong "Definition of Done". This is the overall guard rails for the entire development process. What does everything you produce have to meet. This can include things like determining the coding language that will be used, source control, documentation and the like. A story is not "Done" until it meets the individual User Story Acceptance Criteria and the organization Definition of Done.
Books:
answered Feb 21, 2017 at 16:41
Regardless of the type of project, it is difficult to go wrong by following the INVEST framework.
You've tagged your question as Agile. Are you using user stories? Do those stories have tasks under them? Because those are where the implementation details should go, and it should be the developers who set those up.
The idea behind a user story is not to immediately set up a set-in-stone, comprehensive requirement, but to initiate an interactive discussion from which the full requirements will emerge.
TL;DR
- Give them the problem to solve, tell them why it's valuable, and introduce them to the real person who has that problem
- Better requirements are only a small improvement; forming a cross-functional, self-organizing team removes a major barrier to the development team being awesome.
Requirements
My advice regarding requirements writing is to write them in such a way as to introduce clearly the problems of real people that your developers get to solve in the product. Props to Joel's answer for two great book references. I've found people most commonly use user stories and techniques like impact mapping and user story mapping. To augment these techniques, personas provide a crucial path to empathy with the people for whom the problem is valuable. Such insight allows the developers to rely less and less on you writing specifications in depth. Last consider using some measure of business value to continually educate your developers on the priorities of the organization and it's business model. This post gives one primer technique.
The Team
There's something else I would add. Consider that better requirements are only a small improvement. There's a great article where advice is asked of how best to pound in nails. "Should I use a glass bottle or an old shoe?" the asker laments. One prescient responder points out that a hammer is a much better tool, regardless of any clever advice about when to use a glass bottle or an old shoe.
In your case, it's the composition of your team that provides a bigger limit to agility and effectiveness than requirement writing.
A couple principles of agility provide some guidance here:
Simplicity--the art of maximizing the amount of work not done--is essential.
The best architectures, requirements, and designs emerge from self-organizing teams.
You didn't tag Scrum, but consider the guidance it provides towards those principles:
Development Teams are cross-functional, with all of the skills as a team necessary to create a product Increment;
Consider that beyond improving requirements writing or backlog management, the lack of a cross-functional team provides a system-level impediment to effectiveness. True you can use some clever mitigation strategies to optimize how the api team manages its dependencies or how it hands off it's work to other team; however the problem of queues, latency, inventory, a more complex value stream and increased communication complexity are all categories of waste allowed to exist that are greatly reduced or eliminated by having a cross-functional team. Furthermore, if a team is fully cross-functional, it is easier for them to self-organize since they do not rely upon (or are not saddled with) managing a relationship with one or more other teams. This will likely mean better architectures, requirements, and designs will come from that cross-functional, self-organizing team.
Good API design requires a lot of time and iterations so would not recommend to go with detailed specification upfront.
Organize small workshop to specify initial structure and then deliver first version of the API fast so other teams can adopt and consume it and of course provide feedback.
