Giving Developers Good Requirements

Giving Developers Good Requirements

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.

Need a hand?

I provide full stack development, hiring, management, and coaching services for startups. Click here to learn more, or schedule a free 30 minute consultation.

Want to go more in-depth?

This article is pretty high-level. If you want more details and tactics on how to deal with developers, sign up to get 50% off my upcoming book, Dealing with Developers.

Questions or comments? Drop me a line at or tweet me @remyphelps.