During my dev career, I have many times witness the case that business requirements (and thus, consequently, functional specifications) were not treated with the same scrutiny as the source code. The source code usually passes at-least from one human reviewer that actively tries to improve the quality of it, there are standards defined regarding the quality of the code, and formal tools (usually git) are used to track the changes and the reason behind them.
Business Requirements are ofter described in issues on a separate issue management system and are usually incomplete and separated from source code. Thus it is easier for the code and requirements to fall out of sync (ie a new issue is created for an updated Business Requirement, but the old commits still point to the old issue that holds an outdated business requirement).
To handle both the issue of sub-par business requirements and their "distance" from the codebase I'm thinking of defining a "standard" that would require the business requirements to be stored in markdown files inside the source code repository.
My current approach is:
- Possibly split business requirements from functional requirements (functional requirements are written based on business requirements but are more technical)
- Allow hierarchical structures to be defined by referencing parent requirements.
- Provide meta-data (like front-matter in static site generators)
- Link acceptance criteria to test cases
A command-line utility will be built that will:
- enforce Definition of Ready by presenting requirements without acceptance criteria as not ready
- provide the current status of the project based on the state of each business requirement (not ready, no tests are written, tests are written but fail, tests are written and passing)
- be able to run on pre-commit or pre-merge to either indicate issues or fail the commit/merge
- be able to run on ci/cd to generate and publish the current state of the project
So, what are your opinions about this? Do you see any value on this approach? What would you require to use this approach instead of what you are already using?
Top comments (7)
I believe the only way to keep code and requirements (any documentation about the code really) is, well, to keep documentation part of the code. This is where TDD comes in. Your requirements are codified into test cases. It's a lot harder for your code to go out of sync with the requirements when the corresponding test cases blow up in your face during CI. :-D
That’s absolutely true and I agree with that. As long as we’re only talking about coding/technical requirements which only developers need to understand.
As soon as a third party needs to understand the same documentation your solution becomes useless as they don’t understand tests....
Well, maybe not completely useless. I believe we have gotten to a point technology wise where it's relatively easy to express test cases in DSLs or DSL-like APIs. In almost all modern programming languages, we can write test cases in a way that almost all technical details are hidden, and they can be comprehensible to non-programmers. On top of that we also have tools (e.g. Cucumber) that support near-natural-language test case composition directly.
I believe what I am looking for is for the middle ground between TDD and BDD with the option for free txt for these businesses guys...
Hi!
I've gone a little to far maybe, and I put an essential part of requirements, what we call "Needs", in the database.
So, I have all needs mapped with status, customer, contract and user. There I record:
1) What they want
2) Why they want it
3) How am I going to deliver it
I don't regret this, since it is giving me a lot of benefits in a dayly basis. So, my advice is, as much structure you can get, get it
Actually loving the idea!
This is one of those things where a relation between two things (code and definition) makes sense and is definitely a great improvement!
I'd love to see a first prototype soon!
glad to hear that. btw, you may want to check cucumber and executable requirements it's like what I would like to do (well not exactly)