Product & project management skills for software engineers — part 1: Requirements gathering

Product & project management skills for software engineers

Part 1: Requirement gathering

Introduction and outline

Through my mentors at early-stage startup experience, and later at a more mature organization serving the Indonesian Government, I’ve picked up a few tricks that you may find useful.

I’d like to share around these areas:

1. Requirement gathering, this article
2. Work planning
3. Prioritization
4. Deadlines & estimates
5. When things to wrong

Requirement gathering

Requirements is often a source of frustration and complaints for both engineers and stakeholders. Which makes sense, requirements are where the two worlds touch. On one hand, engineers wish for perfect requirements, precisely defined Figma designs, elaborated edge cases, and a wealth of context. At a growing startup, engineers felt that the requirements they were given was often not clear enough, so they created a template — a format for written requirements with elaborate sections. And the stakeholders obliged for some time. But it was taking too long to hash out and detail all the requirements, eventually the team caves in to pressure and abandons the templates.

On the other hand, business stakeholders wish that once they say a few sentences of requirements, then engineers should know exactly what to do. When I joined an early stage startup, the CEO was directly instructing engineers of what to build. Of course — the CEO had no knowledge how a feature request would be at odds with other existing feature, or that there would be many corner cases that needed to be handled. The engineers obliged, saying “yes, we understand” first, “let us build the feature in the next couple of days”. A poor feature was shipped, not considering many edge cases, and adding additional mess to the codebase due to hacks that need to be added in various parts.

Neither of these are not productive ways of thinking about requirements. Waseem, my manager, shares with me a profound truth: requirements gathering is a communication problem. Treat it as such, and it becomes easier. So here is a few tips:

• Communication, and thus requirements gathering, is best done over a conversation — not async one-way letters with replies over days or hours. The verbal and non-verbal cues, diagrams and scratches randomly put, they will help you learn about the requirements as effectively as possible. For the times we can’t talk, a 5-minute quick ping-pong of chats is still more useful than an async messages exchanged over hours or days.
• Communication, and thus requirements gathering, is a two-way street. Just as it is important for you to know what needs to be built, every conversation is a chance for your stakeholder to build a better mental model of your system.
• Take time to digest and critically think about engineering within the conversation, or even before the conversation — don’t just accept the requirements, think about how you might implement it. What part of code might change? What adjacent logic might need to be adjusted?
• Understand that the key parts of a requirement need to be written down — not just for you to read, but also for your stakeholders. Key assumptions, limitations, main happy path, main negative path. This is part of ensuring no major miscommunication occurs.
• Accept that not all requirements can be written down. Pursuing too much formaility will slow you down.

Now, as I mentioned earlier, perfect templates that suits every company dynamic does not exist. But some templates are proven to be exceedingly useful in a wide range of expressing requirements. Here are loose definitions of what I use to cover 90% of written requirements:

The first is user stories. These are high-level descriptions of how a user intends to achieve something — it addresses why you are building a feature. Your users (not stakeholders, end-users) should be able to read these and understand it. Example:

• Practitioner can review medical note before signing.
• A visitor can explore the marketplace without logging in.

A story does not state much of what to build, let alone how to build it. Yet, I find that it’s a useful artifact. The first usefulness if for discovery of our solution space: stating the impact to the user and intentionally leaving out implementation details, you can often go back to a story to find alternate ways we can achieve the same impact. The second is prioritization within the task: you can cut out fluff from your implementation if you understand which parts will truly affect the user and which one would not. More reading: https://www.atlassian.com/agile/project-management/user-stories

The second is “Given-when-then” acceptance criterias. These are lower-level descriptions of how the system should behave. Your users might not make sense of it — but your business stakeholders, who builds alongside you, should be able to understand it. For example:

Given an unlogged in visitor
When they add items to cart
Then their cart should be populated

Given an unlogged in visitor with some items in cart
When they proceed to check out
Then they should be prompted to log in first.

I find this format very useful in discovering edge cases — and aligning your stakeholders to it. Sometimes just to explicitly mention that a case is left out due to technical limitations. More reading on this technique: https://martinfowler.com/bliki/GivenWhenThen.html

Conclusion

Requirements gathering is a two-way street, an art of communication. Improving your requirements is one of the easy steps to amplify your impact. See you on the next one!