Product Spec

[00:00:00]
>> The product spec. You can notice it, this is actually the longest section on this entire course, but it's probably the most important doc you write on a consistent basis. This gets called a lot of things, I will be calling it the spec for the rest of this course because so far every company I've worked at has called it the spec.

[00:00:21]
But you'll hear this called the product specification, the product proposal, the product sheet, but we'll go with spec here. I'm sure I'll start talking about this, and if your organization has a peculiar name for it, that'll come up.
>> Statement of work.
>> Statement of work, that would actually be another really good one.

[00:00:37]
Some companies will just call it a ticket, right? An email if you're working at a weird company, there's a there's a lot of ways to call this. But it's basically a source of truth that like this describes the thing that we're about to do, and here's all the relevant details for anyone that needs to get aligned on what we're doing.

[00:01:02]
This should not be a a dead doc, which is why email is a terrible place for this. This should be a living doc that as you learn more and as you update more, that this gets updated as you go, right? So another note here, I've given this caveat a bunch of times, but I'm gonna give it here because, again, I think this section is particularly important.

[00:01:25]
I'm going to give you my tips and tricks of how I write product specs, and how I've seen successful ones over the year, and stuff that I've taken from other people. How you choose to write product specs is totally up to you, and you should lean into your own strengths here.

[00:01:41]
So if you hear something here that you are unsure about or you might like, emulate it, try it on, see if it works for you, and you'll either find out, I don't like this, I like this just as is. Or here's this middle ground between what I thought and what Brian's proposing, and I'm gonna stick to that.

[00:01:57]
So I'm inviting you very much to put your own lenses on here and absorb this through that way and then realize that I'm way smarter then you should just do it my way, right? I'm just kidding, please don't do that. So product spec describes some parcel of work, this will usually be some enhancement to a product, maybe it might be a new product.

[00:02:22]
It should be not necessarily exhaustive, but it should link to enough other things that considered together it could be exhaustive, right? So, for example, a lot of my product specs do not have all of the technical specifications or all the edge cases described that the engineers will work on, but I will link to those docs, I will put the designs in the doc, but I will link to the docs.

[00:02:50]
It should be the nexus of your project or the center, right, the town square of this particular project. My product specs match one-to-one to things that go on my roadmap. I don't know if that necessarily needs to be true, but if I have big projects that are split across quarters, I'll have a product spec typically per milestone, or at the very least, one larger product spec that describes all the milestones in depth.

[00:03:18]
But its good not to let these get totally out of control, because if it's 100 pages, no one's gonna read it, right? My product specs, I'm gonna say average, smaller projects, probably two pages. Largest projects are probably ten pages. I don't know, that's finger in the air kind of thinking about it.

[00:03:42]
You can do a half pager for something really small but that would be very, very small.
>> When you talk about your page count, may I ask directly, what it is that you're approximating? Is it the amount that needs to be communicated to describe the concept or idea?

[00:04:02]
So, let me pick a really easy one. I've got a data scientist, Jason put this behind something that we can query, okay? So what I'm gonna hand you is a flask app with one HTTP endpoint that accesses my model, period. That's all I'm gonna give you. But to describe that is a paragraph, unless I get into describing the model, right?

[00:04:26]
So how do you think about what deserves half a page versus what deserves ten pages? You were talking a little bit about complexity, but what features of complexity, I suppose, would cue you?
>> Yeah, I think it's gonna be most driven by how much alignment I'm driving. In this particular case, it sounds like it's you and Jason and you are the only two stakeholders in this particular product project, so less is more here, right?

[00:04:50]
So, I need this end result. Here you go. In which case, by all means, just put it in an email, or a Slack message, or something like that, where wherever Jason would like to be reached, put it there, right? You don't have to drive much alignment between you two, you just need basically a statement of work, right?

[00:05:07]
I need this thing and I have this timeline. Most of the things I work on probably incorporate ten different stakes at the very least. Legal, security, design, engineering, and management, product management, project management like so. At the scale that I work at, I have to satisfy at least 10 different viewpoints with any product spec, and that can balloon based on how big something is.

[00:05:38]
One of the projects that work on touches all snowflake which means that If I have to speak to thousands of people, potentially. That is a very large project spect or product spec, so either one of those are fine. So does that answer your question?
>> It's a great, thank you.

[00:05:55]
>> Yeah, there we go. So I'm gonna give you a rough a framework of how I think about it, and this is just stuff that I found useful over the years. This didn't come from anywhere other than my own brain and stuff that I've stolen from my co-workers that I saw as effective, right?

[00:06:15]
I think this would apply across many industries and then you would just add your own specific flavor to this as well. There's some specific Stripe stuff that we put in here, regulatory was a really big thing for Stripe, and we always talked everything, are we gonna upset anything regulation-wise by doing this?

[00:06:34]
I have less of a problem with that at Snowflake. We still have parts of Snowflake have to be compliant, but we're not worried about compliance on every project. So here is my nine sections that more or less make it into all of my particular product specs that are of any normal size.

[00:06:56]
The executive summary, always the first thing. The problem statements are in the user stories. Goals and non-goals, where I basically say, I'm definitely gonna do this, I'm definitely not gonna do that. The key metrics that I expect to affect, and I'll talk about these in depth as I go through here as well.

[00:07:14]
The rollback criteria, this one I see a lot of people not do, and I'm going to invite you that I think it's a good thing if it applies to your industry. If we don't do these things, or we don't meet these goals, or these goals don't accomplish, and we see that we see no path forward on it, we're gonna roll back to where we were.

[00:07:35]
Because I like to be very explicit with, this is an experiment, everything I do is an experiment. I don't know if I'm right, even if I've done a bunch of research. And if we prove to ourselves that we don't think that we're right, we're gonna go back to where we were, so we don't have dead weight that we're carrying through of all these dead experiments, right?

[00:07:55]
Timelines, design mocks, outstanding questions, and then appendices. Some projects will have less than this, some projects like rollback criteria just won't make any sense, right? Some projects have such short timelines that you don't really need to diagram too much out what the timeline is. Some questions or some projects you just don't have any outstanding questions, some don't have appendices.

[00:08:19]
Some things are like APIs that you're putting out there, so you don't need designs. I guess in this particular section, actually if you were doing an API, I probably would mark out code and when I code I would expect to look like that calls it, I've done that a lot before.

[00:08:34]
But some things just won't have some sort of visual representation, that's fine. But my overarching principle principle here is the same. This is roughly ordered in the order of importance to me, as the product owner, I have what I want you to read from this, right? If you only read the bluff, I'm stoked, right?

[00:08:56]
You got most of my point of view read this, right? If you only read my outstanding questions and technical concerns about my project, I'm very upset at you, you read the wrong part of it, right, I would never put that first. You might ask, where am I gonna do context setting?

[00:09:14]
Typically, in the problem statement. You're gonna give them enough context about the problem and enough context about your proposed solution here and the user studies, then they can understand the rest of the product spec, right?