Giving developers good requirements
Dec 12, 2017
Put everything in writing
This applies to all things in business: get it in writing. Your team should be collecting your requirements in some kind of issue manager like JIRA, Github issues, or Gitlab. If you aren't then it's probably best to stop reading and schedule a free consultation so I can help.
The majority of your requirements and the discussions around them should occur exclusively inside your issue tracker. Any decisions made outside the issue tracker (meetings, calls, Slack, etc.) must be documented in the relevant ticket afterwards!
In order to minimize the bystander effect you should designate one person on the team to be responsible for updating the issue tracker. Traditionally, this is a product owner or project manager. If you don't have those roles yet then simply do it yourself.
Context is critical
Busy leaders need to save time. Unfortunately, this often this leads managers to simply give orders rather than collaboratively working to a conclusion. To give a developer proper requirements, you must include the business context, your thought processes, and why a given task needs to be completed.
Your first instinct is probably "no way, that would take way too much time!" In the long run this will save you time: your developers will begin to think intuitively about the problems they are solving and will save wasted effort due to confusion.
Ask for what you want, not how
Avoid being prescriptive when giving your developers requirements. At best it's insulting to tell them how to do their job. At worst you will inadvertently lead them down time-consuming paths that lead to convoluted solutions. If you are worried about a developer's approach then ask him or her to add a brief proposal in the issue tracker prior to beginning work. From there the two of you can collaborate and nail down the best approach.
User stories
Keeping in mind the above, it's finally time to write some requirements! Follow standard user story format here:
"As a [usertype] I want to [action to perform] so that [desired outcome]."
For example, a user story for this blog post would be:
"As a manager, I want to learn about writing requirements so that I can manage my developers better."
The user story should be the title of the issue in your issue tracker. In the issue description add the context described above along with any mockups, wireframes, extra reading, etc.
Review, ask questions
You must schedule time to review these issues together, estimate effort, answer questions, and revise the issue as needed. Be sure to log notes from your conversation in the issue so nobody forgets!
Be flexible and don't put off decisions
All software teams have constraints. You must challenge your assumptions about these constraints as much as possible! There may be workarounds or "good enough" solutions that help mitigate the impact of your constraints.
A common constraint is a decision that has not or cannot be made. For example, you haven't selected a vendor or library that provides critical functionality or data. I urge you to make as many decisions as quickly as possible; defering them adds uncertainty to your project. If a decision truly must be deferred, give your developers an indication of which direction is the most likely outcome so they can move forward as best they can.