Key points in this video

Before designing a solution, we need to gather requirements.. Requirements are specific tarets the solution needs to meet. Gathering requirements helps us understand:

• the problem we’re trying to solve
• the limits the solution has to work within

Requirements can be functional (relating to how the solution should behave), business (how it fits with the business' plans or goals), architectural (meeting or fitting in with a specific technical architecture)...anything that sets expectations for the solution.

Some ways to gather requirements

Define the problems. Taking a closer look at the problems helps understand the causes and how we can fix those.

Look at any current or similar solutions—what's wrong with them or what they get right.

Talk to stakeholders. Stakeholders are people who are directly affected by the problem or solution (users, developers, managers, testers, executives, and so on). They may not know the explicit requirements, but with the right techniques, you can draw those out. Every class of stakeholder brings a unique perspective, so try to consider their perspective, even if you can’t directly hear from them. Even if you work alone, you’ve got stakeholders (you and your users).

Don't forget:

• Requirements should be specific. Avoid vague, subjective requirements. "The workflow should be fast" is vague and subjective. "The workflow should take less than 10 minutes to make and deploy a change" is objective and specific.
• Requirements aren’t forever. They can change, so your eventual solution should be able to.

Our case study (Venus)

I've attached a list of the requirements we came up with by talking to some (imaginary) people at our company, and looking at problems with the existing solution.

Exercise

Your company is building a Shazam-like service with a public API, Let’s call it Hazam. The API is rate-limited and authenticated, and allows users to upload audio samples to get matches, get stats for a track (how many times it’s been Hazamed), and fetch the most Hazamed songs. They plan to launch the API in a month’s time.

You need to come up with a design for the documentation (and workflow) for this APi. What requirements can you come up with?

Tip: Since it’s a public API, and is a main product of the company, you might also want to hear from the marketing guys.