Comment by sandij | Hacker News Reader

Comment by sandij | Hacker News Reader

We use a combination of Markdown + PlantUML, CSV, YAML, Structurizr DSL, and Gherkin feature files under Git version control next to the code to structure the requirements and examples. A GitHub Actions continuous integration workflow does validations and compiles reader-friendly documentation with Mkdocs. We are experimenting with consolidating more and more of this into feature files.

We structure the project and its related projects hierarchically along service design packages, similar to the “class-responsibility-collaboration” breakdown in object-oriented design.

All of our stream-aligned team collaborates continuously on this data as part of sprints, including analysts, managers, software and QA engineers. We recently started to collaborate with the enabling Risk & Compliance team on the same data, and started doing compliance audits using the generated, Git hash-versioned reports.

Our other teams use similar combinations of data, mostly centered around Confluence spaces which enable some form of traceability due to bi-directional linking.

This sounds awesome but very tech-heavy. Two questions:

- How big is the company? - How did you get non-tech folks onboard with this approach?

Currently we are with between 50 and 100 in total, the team in this example is with 9.

We are building inherently complex systems with high compliance and security impact. So all colleagues are aware that we need to manage a lot of requirements and design knowledge in the progress. So there is a strong motivation to re-use information, reducing work and room for errors. And it helps to have some people passionate about knowledge management and making Git-based workflows easy to use. For example by linking the Mkdocs-generated pages to the GitHub file editor.

We are 12 (and hiring). All engineers. Each of our client projects only need 2-3 engineers.

We specialize in software only medical devices. Engineers handle the design controls with input from product owners. We even got a product implemented and a 510(k) cleared using RDM and a team of just 3 engineers.

https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfPMN/pmn...

It adds a little bit of overhead but we think it results in a better product in the end because engineers are thinking more about building the right thing as opposed to just building the thing right. It also results in a safer product since engineers are thinking about risk as they design and implement the product. Automated documentation generation also cuts down on manual process that required non-technical folks in the first place.

We use a very similar approach at Innolitics when working on medical-device projects for our clients. We've been slowly creating an open source tool to help streamline all of this (https://github.com/innolitics/rdm). We've used this tool to write 510(k)s for three of our clients now and have a couple of more submissions in progress. Each time we go through it we improve the tool a bit.

It handles requirements gathering, documentation generation, regulatory audits, and design documents. We also have been playing around with Structurizr DSL and so far like it quite a bit. We also have a backend that integrates with GitHub and plan to add backends for GitLab and Jira soon.

That's a lot of jargon. Some I understand, some I don't. Seems like it's a good case study for making a graph !

Sounds like a very interesting setup! Is there a blog post or something similar with more details?

Not yet. What aspect would be interesting for you to read more about?

Reply on news.ycombinator.com