6 qualities of a great data spec

If you have real world experience around software development, you know that a good feature spec (a.k.a. business requirement, feature specification, agile story) is essential to getting achieving your desired result.

Unfortunately, many data requirements, if they are written at all, are unclear and imprecise. Often teams do treat data requirements as less important than others, or ignore them altogether. This leads both developer and business owner to frustration, or even worse derails future analyses because the data isn’t what everyone thought. Fortunately, writing a good data requirement isn’t hard if you keep 6 qualities in mind:


Your requirement needs to be clearly different than all others. While we all want to believe our name and description of data is incredibly clear, you need to step back and ask “Would this confuse my grandmother?” Too often data requirements can be confused with each other. To avoid this, clearly distinguish your requirement (but don’t simply state that it isn’t the same as XYZ element – that would make it both not Positive and not Standalone as you’ll see below.)


Don’t make the mistake of having more than one element or specification for the same piece of information. It is not only a waste of storage space to duplicate data unnecessarily, but it will add layers of confusion to your data ecosystem. If you need to add additional sources to an existing data element, update the definition of that element rather than creating another.


“Do not not make it good” — see how confusing that is? While making your requirement positive it sounds like we just need to say “Come on data, you can do it!” having a positive requirement is a bit more. Your requirement needs to be defined by saying what it is versus what it is not.


Your requirement needs to be a complete concept. Making a requirement that simply says this aggregation is a sum of XYZ seems straightforward, but is a recipe for later rework. Without understanding the concept of what you are trying to achieve you may get unexpected results. I still remember a project where we discovered that the developer had stored represented what should have been percentages as currencies; this could have been avoided if both sides documented their understanding of the requirement.


It is too easy to fall into the trap of using acronyms that you and your team use every day, but the developer implementing your requirement is unlikely to have the same context. For this reason you need to avoid all potentially confusing acronyms or abbreviations in your requirement. Does NSFW mean Not Safe For Work, or Never Swim For Workouts?


Finally, your requirement needs to be able to stand on its own without referring to other definitions. When your requirements are split up for implementation, they will often lose the context in which they were written in. You can say that this new requirement sums X and YZ, but don’t state perform the aggregation like we did in M.

While even the most poorly written requirement can be helped along by maintaining friendly and open lines of communication between the business and development teams, keeping these 6 qualities in mind will make everyone’s life a better.

Photo credit: Pascal Swier on Unsplash