Successful PRD format for hypergrowth startups - Introducing Carrot, a programming language for product managers

A PRD serves as the source of truth between business stakeholders, developers, product managers, designers, and QA. Well-written PRDs act as perfect springboards for great features and products to be built. While writing a good PRD is hard, maintaining it is even harder. In a chaotic environment of hyper-growth startups, that’s next to impossible as the requirements change pretty rapidly. Hence, keeping the document updated, communicating the changes upstream and downstream of the SDLC becomes a losing battle pretty fast.

In a rapidly changing environment, defining the requirements in as granular fashion as possible is a potential solution, but then maintaining the big picture becomes hard.

Typical PRDs have the following structure:

1. Context/Background
2. Problem
3. Solution
4. Table of User Stories | Tasks | Acceptance Criterias | Metrics to track
5. UI/mockups

This structure runs into practical issues. Let me illustrate with an example of writing requirements for a shopping cart.

--- PRD starts ---

Context

We run a sports equipment D2C site where we sell accessories, sports gear, and training equipment. Visitors like to browse our catalog and place orders via WhatsApp messages. Now, we will like to provide an easy shopping experience to our visitors by letting them order directly from the site. We have built enough loyal customers that they will like to buy directly without feeling the need to talk to us on WhatsApp.

Problem

Buying our products requires a lot of steps. The visitor browses the website to find one or more products. Then they click on the Whatsapp icon on-site to launch a chat with us on Whatsapp. Then they paste the link of the products they liked, we confirm if the products are available and how soon they will be delivered. Then we share a QR code on Whatsapp for them to make the payment. Post this, we update our backend inventory and create a shipping request to service the order. These are a lot of steps for simple ordering and hence causing operational issues and customer dissatisfaction.

Solution

Build an easy-to-use shopping cart experience on the site with real-time inventory information and payment via a variety of methods.

Skipping all the non-shopping cart-related stories and tasks and just adding one user story.

User Story (US)

As a visitor, I will like to add products to the cart so that I can buy the products together?

Task (T)

1. If the user is logged in and has products in the cart, append the new product to the list of items in the cart

2. If the user is not logged in, add the product to the cart attached to the current user session. This cart may disappear if the user closes this session

3. If the new product has an offer attached, check if the offer conditions are applicable for the items already in the cart and the total and the user type and the geography, and any other relevant conditions

4. Show a visible notification to the user on the successful/failed addition of the product to the cart

More tasks can be added

Acceptance (A)

T1.1. The count of items in the cart increases and is visible to the user in realtime

T1.2. The new item is at the top of the list of items already added to the cart

T2.1. Should work on chrome. Ok for this feature to not work on other browsers

T2.2. If a non-chrome browser is used, show an alert that this browser doesn’t support cart additions without logging in, please login

T3.1. The offer should be automatically applied and the final cart value should be updated in real-time

T4.1. Notification should show in real-time

More acceptance criteria can be added?

Metric

Successful cart additions/Shop page visitors

Status

To Design

Designs

Some mocks will show up here

--- PRD ends ---

Even with just one user story, the above format is painful to parse. There are so many conditionals and frequent references to objects (like the cart) and actions (like login, add a product), making the document fairly verbose. No one likes to read dense documents.

Verbosity is just one of the many red flag issues with the above format.

Let’s say you decide later to not allow non-logged-in users to add products to the cart i.e. you want users to login before adding a product to the cart. Now you will have to change all references, acceptance criteria, etc, everything. This is tedious and prone to human error.

This brings me to the next issue of not having a single view of all the objects and actions. For instance, in the above example, various tasks are acting upon the action of login. So, for even a simple PRD, these add up, and it becomes difficult for developers, business, designers, and QA folks to keep track of every rule that is applicable to the action of login. This leads to product managers missing out on potential issues with implementation up ahead. Only after sharing the PRD with the developer, and after the developer goes through the code base, the product manager would come to know about potential conflicts with other rules already applied on the login action. And then the PRD gets updated, and the cycle repeats.

Apart from this, business stakeholders and other non-technical members will like to review and stay in sync with the entire development. So, documents in simple English will help in ensuring that everyone reads the document and there are no gumption traps of “I didn’t ask you to do this” or “you should have told me earlier”, later (h/t Dan North).

To summarise, the key issues are:

1. Verbose document

2. Frequent reference to product objects

3. Hard to update

4. No single view for all objects and actions

5. Difficult to understand and contribute for non-technical members

I propose a new way of documenting product requirements to handle the above issues. This approach centers on the idea that all stakeholders expect the same behavior from the software and so if the behavior could be documented in an easy-to-understand language, in an object-oriented fashion, we should be able to address all the shortcomings of the classical PRD.

Secondly, it should be easy for stakeholders to view, review and collaborate on the PRD.

Thirdly, it should be easy for the product manager to reuse portions of the PRD, maintain a library of objects.

Fourthly, it should be easy to version control the documents

I propose:

1. To establish a DSL (Domain Specific Language) for writing PRDs and product management in general
2. To establish a standard way to document requirements
3. To use a source control system like GitHub to manage collaboration and version control

Building DSL for Product Management

Sidenote:

Domain Specific Languages are a vast subject and I can’t possibly explain it all here, one because it is out of scope and two because I am not an expert at it. But simply put, DSLs are designed for a specific problem space and are only applicable for that space. This is done for better readability and writability apart from other benefits. SQL is a good example of a DSL as compared to PHP or python which are General Purpose Languages (GPL).

The Thought Process

I started by documenting the keywords and sections that are used in typical PRDs. These were

• Feature title/name
• Background/Context
• Problem
• Solution
• User Stories
• Success Criteria
• Acceptance Criteria
• Designs/UX/Flows

Depending on the product in context, some requirements become mammoth, which is the reason why it is important to define the scope and boundary conditions in PRDs.?

To do so, breaking down the scope into a set of MECE (Mutually Exclusive Collectively Exhaustive) features and defining them individually will ensure that we maintain readability, writability, and maintainability.?

Change in one feature will not impact the other feature for instance. This idea is similar to how typical APIs get developed.

So instead of writing a giant PRD for the entire Epic, we will write small documents covering one feature at a time. A collection of these features will become a release.

To ensure that documents are source controlled, using simple text or markdown format will be better.

Collaboration can be achieved by using GitHub or BitBucket or similar. Such tools provide excellent commenting and tracking features. There is a learning curve though for the non-technical folks, now that the entire lifecycle of pushing, pulling, and updating a file can be done via browser in GitHub, I believe this won’t be a big challenge.

So put simply,?

1. Break down the product into features
2. Write each feature separately
3. In a text file
4. Which is source controlled in GitHub

The typical file structure will look like the following:

Product [folder]

|-> feature1.txt

|-> feature2.txt

|-> feature3.txt

….

|-> featuren.txt

Now, let’s define the DSL keywords, which will help in writing these feature files. These can be borrowed from the common keywords used in PRDs:

• Feature title/name
• Background/Context
• Problem
• Solution
• User Stories
• Success Criteria
• Acceptance Criteria
• Designs/UX/Flows

Since one feature file will contain one feature (one user story), which by definition means one user story per feature file, we can jump straight to defining success criteria and acceptance criteria.

The widely accepted format of Acceptance Criteria is the <Given> <When> <Then> format. I thought of using this as the key method of describing the behavior of the system. It will be good to mention here, that the entire premise of embarking on creating a DSL was to converge on expected behavior which every stakeholder agrees to. The most popular way to describe the behavior of a system is via the Given-When-Then format. Hence, choosing this format was a no-brainer for me.

At this point, something interesting happened. I went into a research wormhole and discovered that this Given-When-Then format was proposed by Dan North and Chris Matts when introducing the Behaviour Driven Development (BDD) philosophy. BDD is a fascinating methodology, similar to TDD (Test Driven Development) but I won’t go too deep into it, it’s just a google search away.?

While reading up on BDD, my leapfrog moment happened, when I ended up discovering Gherkin, a DSL to describe the behavior of the system. Gherkin and Cucumber are used in combination by testers to test if the system is behaving as expected in BDD philosophy.

Gherkin is a DSL written in plain English (or 32 languages) and has numerous extensions in popular code writers like Sublime, Atom, VScode apart from a bunch of software that make it easy to write in Gherkin. Heck! You can write Gherkin in any text file, it is so simple. This was too good to be true. A language that is already prevalent and can do 80% of the hard work as-is. The dream of having a common language to describe products is here.

But my delight was short-lived as I discovered the gaps that existed, which doesn’t allow it to be used as The DSL for Product Management. Hence I decided to extend Gherkin to cover the gaps instead of writing something from scratch. I will explain the gaps as I describe the extended Gherkin.

I name this extended Gherkin - Carrot, as I love carrot pickles.

Introducing Carrot

Let’s go through the keywords of Carrot below.

Let’s use the above DSL to rewrite the PRD about the shopping cart.

--- PRD written in Carrot starts --

FEATURE Shopping cart

As a visitor

I will like to add products to the cart?

so that I can buy the products together


PROBLEM Too many steps across products

Buying our products requires a lot of steps. The visitor browses the website to find one or more products. Then they click on the Whatsapp icon on-site to launch a chat with us on Whatsapp. Then they paste the link of the products they liked, we confirm if the products are available and how soon will they be delivered. Then we share a QR code on Whatsapp for them to make the payment. Post this, we update our backend inventory and create a shipping request to service the order. These are a lot of steps for simple ordering and hence causing operational issues and customer dissatisfaction.

OKR

EPIC

SPRINT


BACKGROUND

Given: User is on the search result page





Scenario: Logged in User

  Given: User is logged in
  
  And: User has products in the cart
  
  When: User clicks on Add to Cart button
  
  Then: New product is added to items in cart
  
  And: Successful message is displayed to user “<Product> added to cart”
  
  And: Count of items in the cart increases in realtime without page refresh
  
  Design: https://figma.com/random-something
  
  Success: Improved add to cart experience
  
  Kpi: add to cart clicked/add to cart successful
  
  Benchmark: 99.9999% success rate on add to cart addition
  
  Impact: Improved cart additions and reduced bounce off
  
  
  
  
Scenario: Product is on offer and user is logged in

Given: Product is on offer

And: User is logged in

Then: Check offer conditionals at Add To Cart

And: Notify user about offer applicability

And: Update cart value

Design: https://figma.com/random-something

Success: Increase cart value

Kpi: #items on offer added/#items added

Benchmark: 10%

Impact: More items added per cart




More details can be added




--- PRD 2.0 closes ---

        

The difference between the two PRDs is fairly evident. Pragmatic PRD written in Carrot is easier to parse, easier to understand, and it is testable as well. In fact, by using REGEX on steps (scenario statements) developers can create tests to check if the scenario works or not (which is the underlying logic behind BDD).

Like YAML, each line starts with a keyword, and details are contained within the line. This makes processing the information very easy and programmable. This format of creating instructions so that they can be parsed programmatically belongs to the world of PEG (Parsing Expression Grammar). Simply put, the idea is to write instructions in plain English with a keyword and an expression per line which can then be programmed. Our specific flavor is based on the Treetop library which is a ruby library that allows you to create parsers that use PEGs.

I have built a VSCode extension called Carrot which can be installed from github. Download it from here - https://github.com/talvinder/vscode-carrot-extension

After downloading, open terminal, cd into the folder, and run “vsce package” to generate the .vix file. Open VSCode and then install the extension using the .vix file. Now it will be super easy to write Carrot files.

In the next article, I will create a sample .feature file and a PRD to demonstrate how teams can develop and collaborate together using Github (or similar source control).

By parsing the feature file, we can identify the keywords and their values. These key-value pairs can be stored to develop a database of all actions and objects. I am developing the Carrot DSL in public and I hope to find interested folks who can help develop the next iteration.

I look forward to comments, feedback, and ways to condense.