Software Specification Fallacies
Over the years, I have read numerous poorly written specs. Don't get me wrong, writing good specs is hard and it's more of an art form than anything else.
The three main "themes" of bad specs I saw over the years, that come up repeatedly are the following.
Simplifying specs too much
This is more of the failure to address corner cases and potential pitfalls. The issue is mainly about glossing over complex scenarios or failing to consider the full scope of the feature or the project itself.
For example, specs that state "set up the database engine" without detailing the specific requirements, configs, or integrations needed can result in an implementation that doesn't meet the project's goals.
More often than not a problem solution is indeed simple, but sometimes complex problems require complex solutions and careful scoping.
It's just CRUD
No, it's NOT just CRUD. Stating this is diminishing the problem solution and oversimplifying the complexities involved in creating software. While CRUD operations are fundamental, they often require careful consideration of various factors such as data validation, security, concurrency, and performance.
There is always more to the problem than just simply stating that "It's just CRUD".
The rest are details
Focusing on the main solution is always the right thing to do but glossing over important details because it's not part of the main solution is a huge mistake. Even if those details are not part of the original problem, they need to be explored before scoping out the solution that the problem requires.
Software projects deal with a high level of complexity and unpredictability. Every module almost always depends on other modules and each of these modules is inherently more abstract than we think it is.
Building software is hard.
Cover photo by Mrillustration
