Software Product Requirements: The Complete Guide How to Write Decent High-Level Project Specifications [+ Example Specs]

Time to read
20 min
Category
Table of Contents
  • Who is this guide for?
  • The starting point: How to check that you actually have a product idea
  • What should be in your specs depends on who you’re writing them for
  • How complex and detailed should high-level project specifications be?
  • Let’s do it! Step-by-step process of preparing high-level project specifications
    • 1. Start creating thingies
    • 2. Group the thingies
    • 3. Give the thingies a reason to live
    • 4. Remember about your users
    • 5. Check if the list is complete
    • 6. Prioritize the thingies
    • 7. Use pictures if you can
    • 8. Iterate, iterate again and then iterate some more.
  • What should the finished specification look like? Download our example
  • For more complex products: use more details (AKA how to add extra sauce to your high-level project specifications)
  • For more mature products: use more tools (only if you have the time and proper skills)
  • Final thoughts

So the day has come.

You got your superb idea for a product. You are sure customers will love it, investors will be more than happy to give you their money for product development—you will change the world for the better.

You can’t sleep at night exploring all kinds of different scenarios how your product will be used. You are playing with customer segments in your head, creating back-of-the-envelope lists of features for future releases.

The only thing you need to do now is to validate your hypothesis with an MVP to make sure you build exactly what the world needs.

But as the saying goes, ideas are nothing without execution. So the most difficult part of your work begins now. 

I assume you are like me: a product manager with a growth-oriented approach, but without a strong technical toolkit. You probably need someone to help you build your product. There could be multiple scenarios:

  1. you work in a large organization and need to “sell” your vision to your CTO/tech department to get some estimates and decide whether to invest in it or not,
  2. you want to create the product with the help of a friendly developer(s), but you still need to share your shiny idea with them to explain what you need to build,
  3. you decided to build it using a software house team and you need to give them input so they can prepare a high-level estimate.

(By the way, if you happen to fall under case #3, we have a full guide on how to compare estimates from software vendors.)

In all of those cases you need a tangible artifact. A medium that will allow you to explain to others what your product is all about and what features it must have to conquer the market (and the world). 

So you need a high-level product specification. This step-by-step manual will help you prepare it (without spending too much time).

Just to be clear: this blog post is not about the development process, agile sprint length, release cadence, communication setup, tools, etc. It is simply about creating the product requirements.

Who is this guide for?

I expect this content will be most useful for products that are 1) not too complex, and 2) at an early maturity stage. If you can place your product on the chart below, this guide should serve you well. And even if it’s not a fit, I offer some additional tips for complex/mature products later in the article.

product-maturity-vs-complexity-1

The starting point: How to check that you actually have a product idea

So you say you got your idea for a product. That means you did the work and you feel the pain of the actual problem you're solving, right?

I assume you probably:

If the above is true, great. You can move right on to the next section.

If not… this is the point at which you have to take a step back. Sorry to tell you this, but if you don’t have a high-level overview of your product, you’re not ready to prepare the high-level project specification. 

To quote one of the gurus, Roman Pichler:

If you can’t confidently state why people are going to use your product, who those individuals are, what makes your product stand out from the crowd, and why it’s worthwhile for your business to develop and provide the product, then you are not in a position to build the actual solution. Instead, continue the discovery work (persevere or pivot), or stop and move on to another product idea. 

If you're working with a software house, you’re in luck—they can probably do discovery workshops for you to help you answer these questions.

If you aren’t working with a software house, you can start by taking a look at our guide on how to run discovery workshops yourself.

Building the product vision is a great exercise in itself that will allow you to create artifacts for further work on the high-level project specification. But more importantly, it will help you to organize it all and make sure your business idea has no blind spots. And that it simply “sticks”.

Of course, the vision may change over time, but when you have a tangible artifact, you can at least track those changes and see the vision evolve.

My favorite tool for doing this is the lean canvas. A single page that paints the full picture of your product, along with:

  • the problem to be solved, 
  • customer segments, 
  • the solution, 
  • revenue streams, 
  • potential costs. 

In short, the canvas includes all the assumptions that you would like to validate by building an MVP.

An example of a lean canvas could look like this:

Click here to download the lean canvas example.

But this post is NOT about creating a lean canvas, but rather about what to do next after you already have it. Creating your product vision is a topic for a whole, separate post, so if you need one, please tweet us @STXNext; I will be happy to prepare one.

Note: Don’t get too focused on the form. You don’t have to use the lean canvas if you don’t know or don’t like the tool.

Just keep in mind the goal, which is to write down:

  • your product goal,
  • the problem it will solve, 
  • jobs/tasks the users will perform, 
  • the benefits that the product will create,
  • and your user roles/segments (along with their main interests and goals).

A simple description in any written form explaining what you want to build and for whom, will do the trick.

Have your lean canvas (or equivalent) ready? Then let’s continue!

What should be in your specs depends on who you’re writing them for

Before you start writing the specs, ask yourself who will be reading it. Your target audience is an important factor deciding what exactly you should include in this high-level project specification. 

If you’re writing specs for your CTO or the tech team inside your organization, they probably already know the context of what you’re talking about. They know the users, the domain and the product you want to build/expand.

In that case, all they need is a simple list of requirements for your next “growth engine”. Additionally, it would be useful if you could point out how the designed solution will impact your existing ecosystem in terms of tech (there may be additional traffic, the product might require integrations with existing systems or changes in the surrounding tech) and business (there may be more customer support requests asking about the new product, marketing may be required, etc). 

If you are preparing a high level project specification for an external party outside of your domain—your developer pals, an external tech team, a software house—or if your product is highly specialized (a space station or gastrointestinal oncology software, etc.) then you might need to be more detailed.

For such cases, try to provide a more detailed business context description and add a simple glossary explaining the common business objects and terms in the field. When in doubt, it is safer to assume that the people you’re going to brief know less about the domain than you think. Any doc or pitch deck that explains the basics on a “101-level” will be extremely helpful.

How complex and detailed should high-level project specifications be?

Whether you are preparing the specification to get a very precise estimate or just a ballpark estimate, remember to define the acceptance criteria for the final number. The more precision you require, the more details you will have to provide and the more time will be needed for someone to analyze it all and prepare the final estimate.

It’s a classic “golden triangle” type of situation: you either get your estimate fast (but it will be less precise), or wait longer for a detailed estimate. 

But no matter how precise it is, you always need to remember it is just an estimate. Don’t bet your house/horse/life on it.

Let’s do it! Step-by-step process of preparing high-level project specifications

1. Start creating thingies

Take your filled-out lean canvas (or equivalent artifact), take the core feature list and start writing. Divide it into separate thingies. Call it requirements, epics, user stories, screens, processes, features, whatever you like; but I will call it the thingies.

At this stage, look for ways to divide the complex problem/solution into smaller pieces. Any item that could be used to drive the discussion further deserves to be a thingie, and the thingies should be estimated one by one. But beware not to fall into the “super-detailed thingiezation” abyss. Try to keep it more or less at the rock level

Graphic shamelessly stolen from a deck by my friend Paul Jurdeczka

To keep the list of thingies complete, try to start with your specific user segments and imagine their journey and specific interactions with your product on a timeline. What do they have to do first? What needs to be done after that? Will they be able to solve their problem once you have all your listed thingies developed and functional?

You can present each thingy more or less in user story format, like this:

“As a [persona from your canvas], I want to [do something within your product] so that I can [satisfy my business goal].”

A simple example would be: “As a good housewife placing an order I want to select a meal size between a 2- and 4-person meal so that I can order food for me and my family.”

You may also find “global” thingies (AKA non-functional requirements) like “I want the whole system to be secure”, “the whole system should be able to support 5k concurrent users” or “the API and all basic functions should have documentation”. If you find one of those, add it as a separate thingy.

2. Group the thingies

Put the thingies in separate groups; let’s call them feature sets. Each set should concentrate on broader functionalities (processing claims, sending payouts, etc.), business objects (customer, order, payment, etc.) or at least on website areas (main page, news, blog, contact form, etc.).

You could try to create a list of sets or business areas at the very beginning, using a mind mapping tool for example. But based on my experience, groups will emerge organically by themselves as you create more thingies. Think of it more as a constant process of analysis and synthesis, rather than defining the general domain areas once at the beginning and then adding detailed thingies to it. When defining groups, go with the flow.

3. Give the thingies a reason to live

Every item on your list should be there for a reason. If there is no reason, you probably don’t need that thingy. The thing you put on the list should be valuable to the user, the business, the dev team or a specific someone else.

If you are a product pro, use the INVEST framework. It’s a set of rules for refining stories/epics. Following INVEST, you need to make sure stories/epics are:

  • Independent (without inherent dependencies on other items),
  • Negotiable (there is space to discuss them),
  • Valuable (for the user or business),
  • Estimable (to a good approximation),
  • Small (so as to fit within an iteration),
  • Testable (in principle, even if there isn’t a test for it yet).

Don’t try to be super exact about it (unless you have all the time in the world). Focus on V.

4. Remember about your users

Use personas from your lean canvas, product vision or problem/solution while writing the feature sets/epics. Personas and user segments will:

  • help you organize the features to fit customer segments/roles,
  • help the tech team understand where to put features in the system.
5. Check if the list is complete

When you have your list filled with items, you should read it a couple of times and make sure there are no blanks.

For example, if you want a user to pay for an order, they should probably be able to create the order first, right?

When your list is complete you can go to the next, most difficult step, which is…

6. Prioritize the thingies

Sort the items in the proper order starting with the most important/valuable ones.

You can do it by adding a release number to the item on the list or by indicating priority through the order of the items (the higher on the list, the higher priority).

After you prioritize the items once—prioritize again.

When you think the list is complete, imagine you have to remove half of those items and prioritize one more time. Cut the stuff that’s not important, and if there are only “important” thingies left—start lowering the priority of important things.

If you want something more detailed than a rough estimation based on your specs (you're aiming for a long time roadmap, for example), you can add more items to the list and assign them to later releases. The tech team creating the estimates will have to spend more time on it, but they should be able to deliver “some numbers” for you to decide on the future.

Prioritizing your product is a topic for a whole separate post, so if you need one, please tweet us @STXNext.

7. Use pictures if you can

If you have visual content of any sort, please use it. Include any mind maps (perhaps the one from point 2 above), UI mockups, images, graphs, paper drawings, etc. “A picture is worth a thousand words”, so put that into practice.

If you don’t have any artifact of this kind, don’t worry; functionality is the most important part and “tech people” can imagine the visual details by themselves. However, there is a risk it may be a different visualization from what you had in mind... 

Illustration by Jeff Patton of Jeff Patton & Associates, based on a concept by Luke Barret of ThoughtWorks

So if you have some expectations, examples or inspirations, include them as links in a dedicated section or write them down as separate thingies. For example, you can create a story such as “As a buyer I want to select my address by clicking on the map (like in Google Maps) so that I can…”

You can also share UI framework styles that you would like to use (Bootstrap, Semantic, Material UI, Ant Design, etc.) or at least some of your design inspirations for the product: links to web pages you fancy, links to the competition, or just comments like “make it look like Facebook but without all those likes and emoticons”. It will help. A lot.

8. Iterate, iterate again and then iterate some more.

Try to start with something simple, fill the list of thingies as quickly as possible and iterate at least 2-3 times based on that. Don’t try to create perfect items from the get-go, because your idea and scope will probably evolve during the creation of the high-level project specification.

Try to keep it short and simple, because “tech people” don’t like to read long docs.

What should the finished specification look like? Download our example

If you follow the tips above, you should end up with something like this:

Download the example specification.

If yours looks similar; good job! You’ve got a high-level project specification on your hands.

And now, as promised, here are some additional tips for preparing high-level specs if your project is more complex or more mature.

For more complex products: use more details (AKA how to add extra sauce to your high-level project specifications)

If you have the information, remember to include things like:

  • the scale: the expected number of users, orders, sell items, or any other business objects to be processed by your product;
  • other non-functional requirements: security, availability, accessibility, documentation etc.;
  • preferred tech stack and deployment environment: if you have something specific in mind write it down along with a justification; it will be great input for tech people for further conversation;
  • high-level business architecture: as my architect friend always says, “there is no such system in the world that can’t be drawn as two rectangles and a cylinder”;
  • specific integrations: if you know straight away what integrations you’ll need, point it out in the high-level project specification;
  • any hard deadlines you’re dealing with: if you’re under pressure from investors or have an important business event coming up, remember to include that information; it will help the tech team understand the urgency.

For more mature products: use more tools (only if you have the time and proper skills)

I hope all of the above seems like a simple task that you would enjoy. If you have more time and more advanced skills, you can use tools like story mapping, prepare a simple business architecture diagram, or dive deeper in terms of technical documentation.

You can try to prepare one of the following UML diagrams, for example*:

  • a use case diagram to show the user types involved with a system, the different functionalities they use and how these functionalities interact/complement each other;
  • an object diagram showing the important business objects in your product, their basic attributes and the relations between them;
  • a component diagram showing your product’s external surroundings and integrations, with interfaces to be consumed/exposed by your solution;
  • an activity diagram to show your complicated business workflows in a visual way.

*You don’t need to use the Unified Modelling Language specifically, it’s a suggestion for the more “techie” people.

Final thoughts

I hope this manual will help you. If you are a “creator” type of person, the process of preparing a high-level project specification should be both fun and simple.

Some final tips on this subject:

  • The outcome of this process should give you a standalone artifact which will help speed up conversations with a CTO, tech team, or software house, and lower the risk of inaccurate estimates.
  • Remember that no document is better than a conversation. After you prepare and send out a high-level specification, make sure to emphasize that the other party should contact you with any questions regarding the scope and the solution. 
  • If you don’t feel like creating a specification, you can always outsource it and use help from people who know how to prepare it. For example, you can use our discovery workshops or hire our discovery/design team.

If you found this post interesting and/or useful, need some further guidance on a specific topic or just want to share your own experience with high-level project specifications, ping me on LinkedIn or tweet us @STXNext.

Good luck with building your product!

Get your free ebook

Download ebook
Download ebook
Share this post