In a sunny green field, a wooden path curves into the distance. The sky is blue with fluffy white clouds.
Unrelated image from to make this post look nicer in social media shares.

A very common question developers ask is what they can do about bad requirements. The internet definitely needs more opinions on it, so here’s mine!

The first thing you’ve got to do is accept you will never get perfect requirements. If anyone knew how to get perfect requirements every time no matter how large the feature was, you would know their name because they would be deservedly famous for finally fixing the requirements problem. Outside of school assignments, the requirements you get are practically always going to be incomplete in some way and probably wrong in at least one way too. It’s frustrating, I’m not going to lie, but that’s just how the job works.

I’m stressing that point so much because I want you to have realistic expectations about how much you can possibly improve your requirements gathering process. If you go in thinking you can ever get perfect requirements every time, you’re just going to be disappointed. On the other hand, if you have more realistic expectations about what kind of improvements you can make, you’ll end up a lot happier with your progress.

Now that I’ve gotten the disclaimer part of this post out of the way, there are some things you can do when you get incomplete requirements or when you work with people who often change their minds about what they want.

First of all ask questions! I touched on this briefly in my post about how communication can make you a better programmer, but it bears repeating. Communicating well is absolutely essential to being a professional programmer, and one of the many reasons it’s so important is that you need to make sure you completely understand the requirements before you build something. Don’t worry about looking stupid, ask questions about anything that you’re not sure you completely understand. Unless you work in a terrible toxic company, nobody is going to be mad that you cared enough about doing a good job to make sure you didn’t accidentally build the wrong thing.

Asking questions can get you quite a ways and is definitely worth doing, but it’s not always enough. Another really useful technique is mockups. When people can see an example and compare it to what they already have, they’ll understand it far better and will be able to give you much better direction about what they really need. It’s a lot of work for the human brain to have to imagine what the finished thing will look like, how it will work, and how you will use it all at the same time. Take a little cognitive load off of your requirements people by asking them to imagine fewer things and you’ll get better results.

There are tons of tools out there for mocking up UI, if nothing else you can throw together a quick slide deck or build a couple simple pages in HTML. Don’t forget to take a lot of notes when you walk your requirements people through your mockup, you’re working with a limited human brain too and you’re not going to remember every detail of the feedback they give you without notes.

After you’ve made some mockups and walked people through them, you may want to build a prototype before building the real feature. Once people can actually use something, it becomes real to people in a way written requirements just aren’t. It’s not because they’re dumb or bad at requirements, that’s just how humans work. Building a prototype will also bring up all the technicaly questions you didn’t realize weren’t answered in the requirements until you started building the feature. Don’t pretend you’re perfect at requirements either :)

There’s another really useful technique for gathering requirements, but unlike questions, mockups, and prototypes, it takes more buy-in from your requirements person or people. That technique is user stories (you may encounter some confusion about use cases and user stories, which seem to be similar but not quite the same thing. I just found out when I was looking for a good link to explain further that the things we call use cases at work, other people call user stories).

To very briefly define user stories, they’re a particular way of stating requirements. The general form is: as a_____ I want to _____  so I can_____. For example: as a blogger, I want to schedule posts for the future so my posts go up on a consistent schedule. It’s amazing what comes up when you think about what you users want to accomplish and why. That kind of context is really important to understand the intent of the feature, but it does take more work on the part of the person who comes up with your requirements and writes them down.

It’s pretty common for people to see all this question asking and mockup making and user story writing as a waste of time that just slows down development. If you’re willing to put in the effort, it can really help to record just how much development time gets wasted because the requirements are bad or get changed all the time. Developer time is really expensive, showing your manager exactly how much developer time gets wasted on building the wrong thing then throwing it out when you get better requirements will likely convince them that it’s worth putting a few more hours into getting better requirements.

Requirements are fundamentally a hard problem you can do everything right and still get a horrible surprise when you’re halfway through building a feature. Like everything else in development, there’s no silver bullet.