Whether you are an established team or a client of an agency building a software product, managing product requirements is a painful multi-party exercise.
When dealing with defining the requirements of a project, the biggest friction point comes from the fact that requirements are often created by non engineering staff on the business or product management side of the company or client. This means that as these requirements are turned into actionable epics/stories/issues, they often need to evolve as the granular details of the specific software implementation come into focus.
Most team and agencies work around the dreaded PRD (product requirement document). The “d” part creates headaches for everyone. Lets look at what a typical process looks like:
- Someone decides that a feature/product/thing needs to be made
- They write down the function in a Google Doc or a Word Doc
- This document goes through comments and revisions between the business, product, design, and engineering teams
- The document is canonized (for agencies frequently into a PDF that goes into a Statement of Work) for use as reference
- Minor changes to the requirements often go undocumented in casual conversations over email/slack/etc while others go through various Change Order mechanisms to update the canonized document
I’ve never seen a project where the original canonized document is followed verbatim.
Compromises, adjustments, and improvements are frequently made along the way as issues come up or technical blocks prevent specific implementations. This results in massive communication overhead to update the requirements documentation and keep teams on the same page.
There is a better way
I would like to sincerely thank @brandonrromano from Carrot for suggesting the idea. What started out as a cheeky Slack message is now a well oiled system for how I’m going to manage product documentation on a go-forward basis.
While there is a small learning curve for first time users, the benefits reaped save many communication overhead hours. Join the movement!
Leveraging GitHub as our store of the product requirement documentation allowed us to create a living document with strong governance for discussing and canonizing changes to our engineering efforts.
A short conversation about approval workflow will land you in a place where no feature, edit, or suggestion is ever left behind.
There are 2 approaches to take here that I believe will work best:
For Agency <> Client projects
- Create repository with PRD as README
- Client requests changes by filling an Issue
- Implementation notes/estimates are added via a Pull Request by agency
- Someone with budget/timeline authority at the agency accepts it
For full-on product teams its even easier:
- Create repository with PRD for a specific milestone as README
- Product team adds changes via Pull Request
- Engineering team approves post PR-comment discussion (if needed)
Besides providing a singular source of truth, this methodology provides a clear audit trail that helps improve processes either in origination of the requirements or in adjusting budgets for agency teams.
We also managed to reduce the number of tools (no google/word docs or emails) that we needed to manage our communications and notifications to Slack pinged the entire team in the appropriate channel on changes that people needed to be aware of. The product we were working on was managed entirely through GitHub, ZenHub, and Slack.
If you enjoyed this article, please be so kind as to spread the love! I always enjoy discussing ways to improve modern team workflow, don’t be a stranger and give me a holler!