What to put in your product specs so you get back exactly what you want

How to Write Product Specs Your Engineers Will Love

Call them what you want. Product specs, product requirements documents, feature specs, JIRA user stories…whatever floats your boat.

Whichever terminology you choose, a document outlining your reasoning for building what you’re building and how you’d like to see it turn out is critical for the success of your product.

We like to call these documents product specs, so we’ll stick with that for the remainder of the article.

Product specs outline what you’re going to build, for whom, and why it’s important.

They are especially important for product managers, founders, and other folks overseeing the development of a new feature from beginning to end.

Btw, if you are outsourcing development you really need product specs.

With clear product specs, it will be much more likely that you’ll get back software that looks and acts the way you expected it to, without driving the engineers crazy by dictating exactly how something should be coded.

The detail and formality of a product spec document depends on well…how detailed and fancy you want to get.

Are you building something simple that fits an existing pattern in your software? Then you probably don’t need to get too crazy detailed (heck, you may not even need a spec if you can communicate what you want in a few sentences).

Working for a startup? A back of the napkin sketch will probably do if you’ll be rapidly iterating and working closely together.

In a fortune 100 company? You may need a more refined and detailed document to make sure nothing gets lost in communication.

Regardless of what size organization you work for, a clear spec is worth the time you put into it.

After all, what’s worse than waiting a few weeks or months for a new feature to be built and then when it comes back it technically does what you asked it to do, but it’s nowhere near what you imagined it like in your head?!?!

Stitch didn’t write a product spec.

Don’t let it happen to you. Here’s what to include in a basic spec that will help your engineers understand what needs to be built and why.

What to include in a product spec

  • Spec title
    • Brief description
  • Why you’re building this
    • The problem you’re solving
      • Why does the customer want this?
      • What will it help them accomplish?
    • Relevant evidence or data for why you decided to build this
      • Analytics and data
      • Quoted user requests
      • Market research
      • Competitor research
  • Who you’re building this for
    • Personas
      • Who will be using this?
      • Does this fit an existing persona?
      • Are they technically savvy?
      • What problems do they face in their life that this may help solve?
    • Customer research
      • Are there any existing habits or mental models that they have to be aware of?
      • What other ways have they tried to solve the problem before?
  • What you’re building
    • User flows
      • What actions will the user take to successfully use the feature?
    • Wireframes, mockups
      • What will the feature look like?
    • User stories
      • What will the user be able to do with this feature?
      • Note: These are SUPER important, so don’t skip over them
    • Copy
      • What copy and microcopy will be needed for this feature?
  • When/how you’re building this
    • Dependencies
    • Edge cases to look out for
    • What is NOT included?
    • How will you know when this is done? What does success look like? Is there acceptance criteria?
    • Milestones you’re looking to hit
    • Deadlines for completion

Leave a Reply

Your email address will not be published. Required fields are marked *