Documenting Your Product – Part 2 – Requirements

This is the second in a series of posts about documenting technology product builds. If you missed the intro or Part 1 – Use Cases, go check them out. At the end of this series, I’ll be providing a bunch of templates and resources to make this process more manageable.

For this series, we’re building a product called PetSitPro, which matches pet sitters with pets in need of pet sitting.

After you’ve documented your Use Cases, you need to translate those use cases into a series of technical requirements for your product. I separate functional requirements (which you covered in your use cases) from technical requirements. Most of the time when people talk about requirements, they’re talking about functional requirements.

Technical requirements are the details about things like system performance, deployment, and other areas to capture before you start building.

Performance Requirements

Maybe you’ve not thought about these explicitly yet, but what are your expectations for your user’s experience on your product?

  • How fast should a page of the application load?
  • What is the acceptable unplanned downtime for the application?
  • How should updates to the system be managed? Is it ok for the application to be down during an update?
  • Does your application need to be geographically redundant in case there is an outage with your infrastructure provider (Amazon, Digital Ocean, Google Cloud, etc.)?
  • How will you know if there is a performance problem in the application?

There is no right answer to any of the questions above, only a right answer for you and your application. And, your answer can change over time. For the initial launch, it might be OK for the application to be down during an update, but as you get more customers it may become unacceptable.

For PetSitPro, I might only be launching in the US initially. I can also make reasonable decisions about my users. Most of them won’t be booking pet sitters at 3 a.m., so I can probably manage system updates in the middle of the night if I need to. I also probably don’t need to have full redundancy between two locations, as booking a pet sitter is not mission critical to most people’s lives. If there’s an outage, I can communicate with my users about when it’s back up.

All of these decisions boil down to requirements statements you include in your documentation:

  • The system must have an average page load time of .25 seconds
  • The system must have no more than 1 hour a month of unplanned outage time
  • The system must support rolling updates with zero downtime
  • The system must notify a list of people if it becomes unresponsive or slow to load
  • The system must support full text searching of all data within the system
  • The system should support geographic redundancy in the future, but it is not required today

You’ll notice the use of must and should in the various statements. You can characterize requirements as must-have, should-have and nice-to-have.

Additional Technical Requirements

Here are some additional technical requirements categories to think through:

  • Should you be able to move from one hosting provider to another with relative ease? This matters as you make decisions about components you might use from a given provider. For example, you would not use Amazon RedShift if you need to be able to move away from Amazon AWS as your hosting provider.
  • What operating system do you want your application to run on? Are you ok with anything? Does it need to run on Windows for some reason for the market you’re trying to address?
  • What language do you want the product written in? Again, are there specific things about your application that require a specific language? Most AI platforms use Python as the primary language as an example.
  • What are the security requirements?
  • What data should be encrypted, if any?
  • Are there regulatory rules such as HIPAA or CJIS that require you to run in specific environments?

As with all of our documentation, the goal with writing down your technical requirements is to force you to make decisions now that might cost you severely down the road if you’ve not at least considered them.

Next up in our series we’ll talk about using sequence diagrams to illustrate system component interactions.