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:
You’ll also need to be articulate in your writing, although I’m not going to touch on that point as much.
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…
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.
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!
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.
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.
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.
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.”
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:
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.
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:
The list goes on and on, but you get the gist.
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.
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.
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.
All free to use from the Almanac Core — the largest library of open source docs ever built.
