Break stuff. Now.

Vague Requirements - The Root Of All Problems

When tools are there yet are underutilized

August 18, 2015

"Criteria of satisfaction: [vague specs + single-state wireframe]. It should work the same as [some other section in the site]. Here's a screenshot [single-state screenshot] of what it looks like."

So tell me, how does the other section work? Guess what, nobody! I know right? Sweeping criteria of satisfactions, very weak task descriptions, "should work the same as". Not really helpful in any way. If you're one of the people who get this often, strap up because you're in for a bumpy ride in a wild chase between business, management, development and everyone else who feels important.


The problem typically manifests itself in one or more forms:

  • A 1-2 sentence description of what happened.
  • A bug report with no log messages.
  • A feature request containing "It must work".
  • A screenshot of a page that tells you nothing about the problem.
  • A very vague to almost no steps to replicate.
  • A single state screenshot. No before, no after.
  • "It's broken" or "It's not working".
  • "Must be fixed", "Release fix" or "Hotfix".
  • A task in issue tracker, but the description is in email or IM.
  • And many more!

Yes, I've been there. Time and again, project after project. Even all together, they still absolutely make no sense whatsoever. It reminded me of my parents when they asked me once "What do you want for lunch?" and I replied with "Anything". They cooked some mushroom dish that tasted like... I don't know. But hey! I said "Anything". I'm held accountable for my actions, and I get what I deserved.

Yes, accountability. Once shit happens, people will start to point fingers. Business will start pointing fingers to middle-management. Middle-management then talks shit to the development team. Development team will then start using blame tool to see who did it. Then the person last on that line validates with the issue in the issue tracker, only to find out that it did follow the issue no matter how vague it was. It passed QA, middle-management reported it to business, who approved and released it.

"Use common sense" excuse


"Use your common sense" they said. This undermines the purpose of an issue tracker. An issue tracker is there to list down what the business requires, and what needs to be done in order for that requirement to be met. If you just tell a person to use common sense, what may seem wrong via common sense might be an intended business requirement. Not following instructions may cause unintended delay.

Follow the issue. What's the worst that could happen? You rewriting code, while the business contemplates on their mistake? It's a whole lot better than rewriting code, while they blame you for not following.

"I have no time for argument" excuse


By saying such, you just made yourself a problem. The purpose of an argument is to engage in a conversation. It is for both sides to open up the problem, propose a solution and defent it. Pulling yourself off an argument isn't necessarily a sign of you being mature. In fact, you are being immature. Leaving from the battlefield means you accept your fate in the hands of the other's decision.

So if you leave your post, don't be coming back and feeling like a boss saying "I still don't like your judgement." You've decided your fate. Deal with it.

The solution

The solution to the problem is very simple: Time, detail and context.

Yes, I'm no stranger. I answer questions in StackOverflow which range from very detailed and annoying to read, to very short yet very vague. Askers will range from those who have no names, to ones that have 500k reputation. Answers will range between fast and correct, fast and terrible, slow and correct, and those that get downvoted for outright wrong.

Just taking a few minutes to reflect on the problem will go a long way. Taking time to write the details of the issue, taking into account the team that does it will help a lot. Taking time to reflect on the fix prior to QA will also go a long way. Don't rush, test it yourself. It's faster than going rounds with the QA.

Time will come for those who wait. For those who don't, shit happens.


In the event that shit happened and everything fucked up while you just did your job, here's some tips you could follow to save your sorry ass from being thrown under the bus. That way, in case you get cornered, you can pull up one of these aces and say "Booyah! In your face eyhoules!!!"

Make tasks clear

If it's a bug, make them write detailed steps to replicate the thing. Otherwise, declare as no-fix. If it's a feature, make them write everything they want, otherwise, it's a no-go. Make sure everything is jotted down to the dot in the issue tracker. No exceptions.

Keep notes

Keep a history of all your conversation. This includes email, chat, even video conferences. Take down notes, put in dates, take screenshots. That's because no matter how you try, people will always resort to using a conversational channel which is convenient, but whose history is never guaranteed.

Commit meaningfully

Time and again, I've been told to keep my commits meaningful. I never thought commits can be used this way. Commit messages should always be meaningful, in that it should describe the summary of the commit, the feature implemented, why it was implemented and how it was implemented. Details of quirks should also be included, not as a way of keeping to-do's but to know the existence of such.