Shuhaid Lambe
Shuhaid's Blog

Shuhaid's Blog

How to document your product requirements

How to document your product requirements

Shuhaid Lambe's photo
Shuhaid Lambe
Β·Jul 18, 2022Β·

6 min read

Play this article

Welcome to the series How to build a tech product. This article covers, how to go about writing requirements for your product.

Requirements scoping sets the tone for your product. Well thought through requirements, play a large role in a project's success. Lengthy project requirement documents, whether technical, functional or non-functional, are a snooze fest for most people to read through.

On the other hand, put your self in the requirement writers shoes. Imagine someone who has painstakingly tried to create a document which covers every scenario that they could possibly imagine. In spite of all their effort to create an exhaustive requirement document, there is a good chance something is going to get missed when the implementation hits the road.

Reading and comprehending a requirement document is just part of the challenge. Here are some other challenges you may encounter as a product owner who is writing requirements for your product.

  • Requirements need to be read and understood by team members so that everyone in the team is on the same page. A typical team will consist of folks with different skill sets and different levels of tech savviness
    • Business stakeholders like sales, marketing, clients, operations, finance and more
    • Developers / QA engineers
    • Designers
    • PMs
  • You are dealing with teams spread across geographies. Places where English is not their first language. A lot could get lost in translation in such scenarios, through no fault of anyone.
  • You have a set of requirement documents which have captured everything needed on day 1. Now, how do you keep this current when changes start coming in thick and fast?
  • You would like your development teams to have a holistic view of the project even though their focus areas maybe limited to a set of components from the entire project.

Documenting product requirements still remains, one of the parts of the software development cycle that has seen little or no innovation.

Personally, I have come to believe that using a Mind map to capture a products requirements is the simplest way to alleviate these challenges.

Open your mind

Check out this mind map describing the sport of Tennis to a novice

Tennis-mindmap.png Tennis mind map from wikipedia

This map covers the scoring mechanism, playing surfaces, key tournaments, key principles and type of shots in the game. Along with this it covers trivia like the fastest serve and other bits of information. Enough to upgrade someone from a novice to an decent level of understanding of the sport.

The same level of information if covered in a document would be verbose and could lose a high percentage of readers mid-way. Writing information in form of a mind map increases the chances your readers will go through everything that you have documented. Moreover, this format also helps to explain concepts in context to the environment they belong in.

Let's take another look at the Tennis mind map to understand a concept in context to its environment. Say you need to recollect which Grand slam is played on clay courts. The information is present in the Tournaments node. A Grand slam is type of a tournament, there are 4 grand slam's in Tennis and one of the Grand slam is played on clay. This tournament is called the Roland Garros and the venue for this tournament is Paris.

vladimir-tomic-OtcRKNgWWQ4-unsplash.jpg

Mind maps can not only answer the question at hand, but also help in adding context and relationship with the environment in quick time.

As a product owner, providing your team members with this level of context and understanding is a super power πŸ¦Έβ€β™€οΈ

How to start using mind maps to document product requirements

  1. To start mind mapping you need a tool, try FreeMind it's free and makes it simple to create and distribute map files.
  2. After you have downloaded and installed FreeMind try documenting a project or module you are working on.
  3. Put the name of your project or the module you are documenting in the first (root) node. From the Format menu option click on Automatic layout. This will ensure your map looks pretty right from the outset. You can edit these formatting options as you go along.
  4. Identify your key stake holders and put that as your first set of nodes after your root node. For example for a help desk ticketing system Customer & Support team could be the the first set of nodes.
  5. Next up, identify the key use cases for each of these stakeholders. For ex. A customer would need ability to raise a ticket and check status of their tickets. You can add subsequent nodes to these nodes and detail out the fields and rules associated with the node you are working on.
  6. If you need to add an explanation or a note to a particular node, click on the node and navigate to the View menu option and click Note Window and enter your text. You can also link to supporting documents / calculations / sheets / designs. This helps to place your supporting documentation within a context

Each node comes with a context as it lies in a certain position within the map. If while reading the user loses context, they just need to back up within the map to find context. Detailed mind maps can be quite large and can cover every aspect of your project in detail. Here is an example of a completely zoomed out mind map of a product I helped build. The level of detailing in your mind map should depend on the size of your project, team make up and product delivery capability. image.png

Advantages of using mind maps in product development

  1. Mind maps provide you the ability to put a paint a high level picture of your product requirement, while detailing the minutest aspect of your product at the same time.
  2. The nodes within the map are completely fungible. As your product requirement evolves, you can move the nodes to different sections, replace or remove them with ease. Imagine doing this in a requirement document 😱
  3. Mind maps can be consumed by both technical as well as non-technical team members with ease. You can easily mark nodes with icons that are specific to an audience. For example, nodes meant only for tech folks can be marked with πŸ›°
  4. Where required you can snip and send only a few nodes and its children, instead of sharing the complete map. For example, you have contracted a software vendor to build a specific part. Snip and send only the part of the map (nodes) that is required for them to complete their build.
  5. Every node can be supplemented with documents / excel sheets / UI designs/ web links and more

Making things simple to understand does not mean neglecting details.

Now that we have seen how to go about documenting your product requirements, lets understand how to define your product architecture


An earlier / shorter version of this post was written and published by me on dev.to

Β 
Share this