back

by jtwaleson·4y ago·view on hn ↗
This is super interesting and incredibly difficult. In some regulated environments, like medical devices, you MUST keep track of requirements in your product's technical documentation. I work on a Software Medical Device product and have seen tons of workflows at similar companies. There are many different approaches to this and none that I have seen work really well. In my view this field is ripe for disruption and would benefit from standardization and better tooling.

Here are some options that I've seen in practice.

A: put everything in your repository in a structured way:

pros: - consistent - actually used in practice by the engineers

cons: - hard to work with for non-developers - too much detail for audits - hard to combine with documents / e-signatures

B: keep separate word documents

pros: - high level, readable documentation overview - works with auditor workflows - PM's can work with these documents as well

cons: - grows to be inconsistent with your actual detailed requirements - hard to put in a CI/CD pipeline

A whole different story is the level of details that you want to put in the requirements. Too much detail and developers feel powerless, too little detail and the QA people feel powerless.

1 comments
For option A, how do you put the requirements in the repo? Another user mentioned the possibility of having a "req" folder at the same level of e.g. "src" and "test". Maybe the file structure would match that of the other directories? And what do you use - excel files, word docs, .md files, something else?
There are some tools like https://doorstop.readthedocs.io/en/latest/ that streamline it.