Writing Engineering Requirements Documents – ERDs

What is an ERD?

At FloQast we have a constant backlog of work and ideas flowing from the Product team to the Engineering team. Frequently those ideas for new features are presented to us in the form of a PRD (Product Requirement Document) and often times it’s critical for us as engineers to transform those ideas into our version of an ERD (Engineering Requirement Document also known as a Technical Requirement Document).

An ERD serves as a blueprint for how the engineering team is planning to solve the problem presented to them. It presents a way for our engineers working on the feature or product to digest the requirements before writing any code. Along with creating a better understanding of the problem it also allows time for the engineers to attempt to poke holes at the proposed product and their solution.

What should an ERD contain?

With our ERDs there’s no strict rule as to what it should contain, but at a minimum it should have a rough translation of product specifications to technical specifications. Often times that may include ideas for new schemas or changes to existing schemas along with architectural diagrams representing code, infrastructure, and tools.

The document should be thorough, but not overly so. We’re creating a high level view of what’s to come, but just like any good plan it should remain flexible and fluid. Given that, it’s often up to the point person working on the ERD to determine what would be most helpful for it to contain so that it can serve as a guide for their team.

In general I’ve found success with my ERDs containing the following topics:

• MVP Functionality: This is usually at the top of the ERD and details a summary of what this ERD intends to output.
• Architecture: In this section I usually contain up to three sections for Existing, Future, and Near Future architecture. The usage of these sections depends on what architecture may already exist and whether or not the MVP/PRD calls for an incremental solution. I utilize diagrams the most in this section to help detail how the various areas of our codebase and infrastructure will work together.

• Areas of Concern: I use this section to help detail any significant concerns that we’ve identified during the ERD research and creation. The topics in this section will translate to spikes, time-boxed user stories used to clarify any significant doubts around potential solutions. Instead of carrying that doubt into the development process, these spikes are worked through the sprint like any other issue but the resolutions are used to create new issues with clearly defined objectives.
• Schemas: Having a detailed view of the data we’ll be working with for the project is always important so it warrants its own section within the ERD.
• Implementation/PRD to ERD Map: Finally, after the ERD has been solidified and we begin to break it out into tickets I add a PRD to ERD section. This is where we connect the tickets we’ve created back to specific topics within the PRD. Given this we can quickly see how various parts of the ERD map to specific business value that’s been outlined in the PRD.

Where to start with ERD creation

Often times the hardest part of an ERD is the initial start. There’s most likely a lot of information we’re trying to translate in the PRD and finding the best place to start will make writing the ERD easier.

Generally when writing an ERD I first consider the problem from the ground up. Having a sound understanding of the data I’ll be working with will help inform the rest of my decisions. With the data and its structure in mind I can begin to visualize the various services or functions that will need to work together, helping to formalize our architecture or investigate existing. From there I typically have a foundation that will allow me to understand how the features of our product will mesh with our architecture. By this point I would have most likely had multiple questions for the product team as I find technically difficult areas in the code, functional edge cases, or just to seek clarity on how a feature should work. This pattern has held true for me whether I’m starting a project without any existing code/data or I’m starting with something else already in place.

Afterwards I may find that the engineering plan seems a bit grandiose. The new tools, codebases, schema migrations, etc. that I’ve decided are necessary for the project might double the time I originally thought it would take. This is the perfect point for this to occur. With our ERD draft in hand we can now look at presenting our findings to our product team along with a rough estimation to complete the work. From there we typically find that we can work with the product team to trim some of the fat off of the project and create a more lean MVP which should also translate the same to our ERD. If the project is already as lean as possible, then perhaps we’ll need to look at creating phases for our implementation and document that in the ERD. In the end, the ERD should best represent how our team looks to solve the problem presented to them in a way that can also be demonstrated to our product team.

Final Thoughts

Finally, we’re not afraid of treating our ERD as a living document. As scope increases or decreases with the feature we’re working on it can be helpful to continue to revise our ERD. This living document will help to keep tabs on what was planned versus what was implemented, serve as an introduction to team members starting in the middle of the project, and finally, when all is said and done, serve as a catalyst for discussion during a project retrospective.

A well crafted ERD represents the hard work and time that the engineering team took to fully understand what they’re being asked to create and how that might impact their codebase. Without a proper plan it’s all too easy to watch your team slip and slide with scope as they discover new areas of technical concern or fail to understand how a feature is expected to be handled architecturally.

I hope this article has given you some nice insight into how we plan our development at FloQast and an idea for how you can write your own ERD.

Kristopher Morris

Sr. Software Engineer. Works at FloQast. Enjoys popcorn.