Documenting Your Product – Part 1 – Use Cases

This is the first in a series of posts about documenting technology product builds. If you missed the intro to the series, read it now. At the end of this series, I’ll be providing a bunch of templates and resources to make this process more manageable.

When most people think about writing documentation, it usually inspires a reaction something like this:

Screaming cat

Believe me, I’m right there with you. It’s somewhere between getting punched in the face and getting struck by lightning on the pain meter for me. I’d much rather jump in and go.

However, putting even minimal practices in place will force you to, as my friend Ricky Spero said, “Separate your thinking from your doing.”

For purposes of this series, let’s assume we’re building a simple product that lets our users find a pet sitter to take care of their furry best friend. We’ll call the product PetSitPro.

Here we go.

Different Kinds of Documentation

There’s at least two different kinds of documentation around a software project.

  • The “Where’s all my stuff” kind of documentation that we’ve covered extensively in the past
  • The “What We’re Going to Do” kind of documentation that we’re going to cover in this series

Start With What – Use Cases

Sorry, Simon Sinek. I know you like Starting with Why, but in this case we’ll assume you’re already beyond the “why” of your project. In the case of PetSitPro, we’ve got a few different kinds of users who need to do different things. People call these User Stories or Use Cases sometimes interchangeably. However, a Use Case in my mind is more technically focused rather than a User Story, which is more business focused. I think about User Stories as belong to the Product Definition, whereas Use Cases belong in the Technical Specification.

Let’s assume we have two roles in PetSitPro: Pet Sitter and Pet Parent.

User Story:

As a Pet Sitter, I need to be able to search all Pet Parents who need someone to take care of their dog within a 10-mile radius of my house for the next month

Use Case:

  • Actor: Pet Sitter
  • Description: Pet Sitter needs to be able to search all Pet Parents who need someone to take care of their dog within a selected radius of their provided address
  • Pre-Conditions: Pet Sitter is registered, logged in, has given us a base address, and has indicated they prefer to take care of dogs
  • Actions: Pet Sitter selects the desired radius, dates available, and clicks ‘Search’
  • Outcome: Pet Sitter is presented with a list of possible Pet Parent opportunities. Pet Sitter can then select a particular entry and get more details
  • Alternate Outcome: If no results are found, the system should allow the Pet Sitter to change their search criteria and search again. The system might suggest to widen their preferences to include cats or ferrets, as some of those are available.

As you can see, the Use Case provides a lot of detail to the development team that doesn’t exist in the User Story.

But what about wireframes? Can’t we just use those? Wireframes are tremendously valuable, but the additional level of detail you can capture in a more technical Use Case I find to be a great accompaniment to the wireframe.

Let’s explore what we now know about this system just from this one use case:

  • We need to provide a system where some features are only available behind a login
  • We have multiple roles who can do different things, so we need to be able to manage what roles a user is in
  • We want to be able to geo-fence the search, so we need a mapping API. We have to now go evaluate and pick one of those
  • The system has to support preferences for each kind of role (Pet Sitters who like only dogs, Pet Parents who only want people over 30 to watch their pets, etc.). That means managing and being able to search for these attributes. We’ll need screens for each user to manage those, and an “admin” screen to add new kinds of attributes down the road
  • We have to be able to determine that someone who likes to take care of dogs might also like to take care of ferrets in case there are no dog jobs available
  • We have to be able to show a list of results, likely a way to page through them, and a way to show a Job Details page where the user can take action.

Each one of these items in the list above are now Requirements that need to be captured and make their way into the technical specification unless someone decides differently. I hope you’ll notice how this one, simple use case has created potentially tens of hours of work. All that work costs your company money. Not to mention the need to integrate an external mapping API, which will also cost money every time you use it.

I also hope you’ll notice that if we’d just taken the User Story at face value, we would’ve lost the details around how to handle when things don’t go as expected, or how we need a flexible attributes configuration for the application. Nine times out of ten these details are in your head but they’re not written down. As a result, you get three weeks into development, realize you’ve missed an important detail and have to unwind or fix a bunch of work, all at $60-100 per hour. Sucks, no?

Use Cases force you to capture those details in your head that drive costs and time through the roof on a development project.

There are literally thousands of articles on writing Use Cases, so do some research and find the methodology and level of detail that suits you and your team. There is no right way, only a right way for your situation.

Next up in our series we’ll talk about how you take your use cases and turn them into detailed technical requirements. Who knew documentation could be so much fun? Right?