Get our latest stories
delivered right to your inbox every week

A Practical Approach to Writing Product Specifications

Writing great specs is one of the key skills of a product manager. Level up your specs with this step-by-step guide.

By Nirob Ahmed

Jul 13, 2022

Required skills for Product Managers

Out of the many skills a product manager needs to perfect, one of the most important yet less talked about is the ability to write clear, yet detailed, product specifications (specs). Unfortunately, product management books and blogs are high on philosophy, but low on practical resources!

This is a real issue, especially for junior product managers. They’re often told that they’re accountable for the team’s velocity of execution, for the quality of the products, and that they need to maintain a good relationship with their developers. But they’re not always given the tools to do that.

While there’s no substitute for proper mentoring from a veteran PM, I hope this post can shed some light on what it means to write a proper, simple and clear spec.

In order to write a good spec, you’ll need a few things:

  • to be detail oriented, but also know what to leave out
  • to be technical enough to understand the challenges their developers will encounter
  • and have the UX vision to know how small details might affect the users

You’ll also need to be articulate in your writing, although I’m not going to touch on that point as much.

The Challenge of Writing Product Specifications

The task itself seems simple enough: “You have a chat app that accepts messages from various sources, such as WhatsApp, emails, Google Docs notifications, and more. You’d like to add the option to show images. What are the details your developers will need?”

For the purpose of this discussion, you can disregard the need to upload new images, and assume that it’s already working.

Pretty straight-forward, right? Take a minute to think about it. It almost seems like a one-line user story, doesn’t it? “Hey dev person, please add images to the chat”. On to your next meeting!

But wait a minute…

The process of writing new product specifications

There are a few things you should do whenever you write a new spec. I’m going to mention some, although I’m not going to focus on all of them in this post.

  1. You can and should write down the various use-cases, or at least the main ones.
  2. If possible, look for online articles about best practices. Most of what you’re doing has probably already been done by others who have given it a lot of thought, and who have made mistakes you can learn from.
  3. You should understand the data. This might be somewhat controversial, as some PMs believe you should leave the tech to the techies, but I’ve personally always found it super useful to get down to the details. It also helps you get real-life examples of chats that actually use images, and make sure you don’t forget any use-cases.
  4. Sometimes the important details can actually come from the tech itself.

Let’s start with the last point. Take a look at the properties an image has (for example, in this page). The list is long: align, alt-text, height, width, size…

There are two reasons for why this is helpful: first, some really smart people have already given some thought to what is important about images. The second, and more important, is that these properties are what your developers will need to face when implementing your spec. The more you understand that, the fewer gaps you’ll have between spec and execution.

Okay, let’s dive in!

Be sure to include the obvious in your product specifications

The first thing to note about any chat is that it has two sides: the user (commonly displayed on the right), and the people they’re talking to (AKA “the other guy”, commonly on the left). You want the image to be aligned within the text-box, so that your images will be right-aligned and the other guy’s aligned left.

While it’s a detail any half-decent developer should realize on their own, it might still be better to specify in advance, if only in one line. Also, you should always make sure it’s a part of the design.

Great product specifications also include edge cases

Okay, this is where we get a bit technical, so bear with me.

A common thing you should consider in any spec are the edge cases. In our case, the images might be very wide or very long, and they might be very large or very small.

Image aspect ratios

If the image is very long, you might get a message you have to scroll for a long time to get to the bottom of. This usually makes for pretty bad UX. The way most products handle this is with a fit.

If you come from a coding background, that should be a no-brainer for you. But most PMs aren’t familiar with the types of image-fits out there, the main ones being Fill, Contain, and Cover (see image below). Facebook Messenger, for example, uses Contain within a 1:1 box, while WhatsApp uses a Cover in a 1:1 box. Personally, I find Facebook’s solution more elegant. In any case, never use the Fit option for anything.

As you can see, this is a product decision. If it’s not mentioned in the spec, you just might end up with squashed images.

Image aspect ratios

If we don’t consider the image sizes, two things might happen: an image too large might break the page layout, and a picture too small might get pixelated while fitted. Here’s a bad mockup of what it might look like:

Again, while a decent developer should know to prevent those edge cases, you should mention this in brevity. There’s also a product decision here: if you direct your dev to do a fit — by definition, it will also fit the smaller images, which causes the pixelation. The spec should read, in this case:

“Contain the image in a 1:1 box (as in the design), but only scale the image down — if the image is too small, just align it to the side.”

Product specifications identify use-cases and user flow

The feature itself is simple: showing images. But the specific scenario with the user is usually more complex than that. Why does the user need the image? What might they do with it? If, for example, we’re working on a social app, we’d probably like to encourage our users to share the image. And if we’re working on an app for designers, a common scenario might be for the recipient to draw and mark areas on the image. Other common behaviors are to download the image, and to view it in full screen.

The questions you should be asking yourself are:

  1. Is this required for a first version? Will my users be disappointed if this doesn’t exist? Is it a major use-case for them?
  2. How much work will this take? Is this something my developers need to build by themselves, or is it out-of-the-box behavior? This might call for a small research task for your developers a couple of sprints before you plan to actually develop it.
  3. Will it bother any of my users if we add this? Will it complicate the UX in any way?

It is common for your developers to have a few libraries they can choose from with some of these behaviors already implemented. In that case, your job might not be to spec out the download behavior, but instead to choose the library that best suits your needs.

Other things to note when writing great product specifications

So far we’ve covered the most important things about our specs, but there are a lot of other details we should take into account. Here are some:

  • Mobile vs. web: if you support multiple platforms, are there differences in the details? In fact, in most cases, these will be two different teams working with two separate versions of the spec.
  • Multiple images: Does your data support this? If so, will you show the images one by one, all in the same message? Say you have 10 images — will you show all, or show 3 and then have a “+7” to open the rest of them (see image below)? Depending on the specific use-case, this can probably be an advanced feature for later versions.
  • Inline images: In some chats, you might have an image attached before or after the text, while in others (email, in particular), you might see images in-line within the text. Does your use-case support this? Another important question you should have an answer for.
  • Attached images: How will you see attached images? These usually show without a preview, and can be opened on click/tap.
  • File types: Will you support all file types? If so, what are all possible types? If not, which formats aren’t supported, and why? Note that some file types might require more work than others — this sounds like another preliminary research task for your dev team!
  • Error messages: What happens if you fail to show the image for some reason? Do you show an error icon instead? And this brings us to the next item:
  • Accessibility: Do you make sure all images have alt-text? How will they be accessible to visually impaired individuals? This should be a part of your general product guidelines, as it might also have legal implications.

The list goes on and on, but you get the gist.

What NOT to put in your product specifications

As you saw, our one-liner quickly became a full page or two of text. We need to make sure it doesn’t go beyond that. It’s 2022, and you don’t need a 15-page PRD for every small feature.

An important guideline to keeping your specs short and clear is that whatever can be explained by the design, should only be explained by the design. There’s no need to write “put the button on the bottom right corner of the screen”.

Another thing I find useful is to write in ordered, logical sections. These might be similar to what I’ve written above: fitting images, downloading images, etc.. This might be a personal style preference, but I found that it’s much easier for developers, as it gives them a kind of a checklist for their own tasks.

Making sure you have everything

A question you might be asking yourself at this point is — how do I make sure I don’t miss anything?

The simple and straight-forward answer is — you don’t. You do the best you can. But assume that you will always miss some things. Here come the other important aspects of product management. Give your team enough of a heads-up to go over the spec. Make sure they feel involved enough to point out what’s missing.

Never play the blame game when something goes wrong (which it will). Make yourself available to them a few times a day. QA properly and release gradually. Make time in the sprint after release to fix bugs.

Summing up

Okay, so much like some of my specs, this post is already longer than planned. We’ve seen how sometimes, even what seems like a one-line spec can actually have a lot of important details.

In his classic article How to hire a product manager, Ken Norton mentions that the first thing he looks for in a product manager is “raw intellectual horsepower”. I couldn’t agree more. What this means in practice is that you need to be able to take a task, apply analytical skills, break it down and look beneath the surface.

A spec is not a to-do list. A spec should represent your user, and how they interact with the feature. And it should represent the dev team, and the challenges they’ll face while implementing the solution.

Finally, the best advice I can give is the one I started with — there’s no replacement for proper mentoring. If you have more experienced product managers on your team, reach out to them. If you’re flying solo in your company, reach out to others outside your company. There’s a saying in Hebrew: “more than the calf wants to suckle, the cow wants to nurse.” Go, find your cow.

Templates to Help You Get Started

All free to use from the Almanac Core — the largest library of open source docs ever built. 

More stories on: