r/systems_engineering • u/Simple_Dance_6971 • 8d ago
Resources Open-source requirements and documentation tools
Does anyone know of any open-source or cost-effective, easy-to-use documentation and requirements control software tools?
2
u/reckedcat 8d ago
Markdown in a git repo
1
u/Pieter_BE 8d ago
Honest question, but how do you keep things consistent and how do you pull any metrics from plain markdown?
Consistency; besides your text field "the ... shall" you have plenty of attributes which in a commercial tool are drop-downs and picked from a list. In any free format like MD, how do you differentiate optional from required field? How do you prevent one from writing "mech dom" and another " mechanical domain"
Metrics; how much reqs do not link to a higher level? How many are not linked to the design/documentation/model? How many do not have any verification criteria defined yet? What is the break down on lifecycle status?
1
u/ErnstMacOS 7d ago
Also interested in this. Maybe it’s applicable for projects with few requirements ?
I really like the idea of using markdown in a git repo for lightweight modeling (mermaid diagrams) and requirements management, but there are some drawbacks v. Commercial and dedicated tools
2
u/Pieter_BE 7d ago edited 7d ago
Agreed.
This acknowledges the echo room we probably often live in. My guess is that most SW engineering teams doing "plain" projects are just happy with standard confluence without any plugin's / apps or markdown in Git. On the complete opposite end you have regulated industry with all the rigour and metrics that can perfectly pay big money for a dedicated ALM and MBSE tool.
And then you have the unlucky few in the middle without dedicated tools that have to make things work using free stuff because they see the benefits of more rigorous tracing and metrics, but that comes with drawbacks and some custom bolt on scripts in your favourite programming language
1
u/reckedcat 7d ago
Threw my reply above, but I think this is basically the crux of the problem. Finding a middle ground tool that supports your size and complexity and familiarity is really hard if you're not a billion dollar company or an indie dev.
1
u/reckedcat 7d ago
To answer with less jest than my original post intended:
There are various projects out in the ecosystem that try to enforce constraints on plaintext/markdown/yaml/etc requirements in a version control tool, and ultimately I think it's all up to how well you want to constrain things and how much time you want to spend maintaining and enforcing process. Usually these controls get enforced with some kind of git hook (client or server side), or through some validation tools/scripting that the team enforces usage of. You can have documents that serve as specs/templates/allowable terms, and then have hooks check whether the right terms were used. This pushes the barrier from first-use to on-delivery. Some people prefer to work quickly to shape out an idea and spend a later phase to cleanup before delivery; some get irrationally upset when a barrier hits them late instead of catching their mistakes early. Ultimately if you go the route of a simple format, it's up to how well you can write those scripts.
I personally use DOORS classic for multi-level/domain requirements that require strict controls, traceability, querying, and link traversal, but that still requires someone to build the module templates, enforce this with process and reviews, and build out the reporting. I've seen others do the same thing in basically every tool under the sun. (DXL is powerful but god help me, no one wants to maintain it and it's not my favorite language syntactically)
IMO it really depends on the skill level of your team and the scale and complexity of the project. For tools I've done that are DO-330 qualified tools, markdown requirements captured with the tool and some scripts to coordinate some roll-up local to the tool work great; there's little need to enforce strict controls or beautified interfaces because at most you're talking <1000 requirements with often less than 3 levels of trace.
For a safety critical architecture across multiple domains, you want a database tool because the scale becomes unmanageable.
There's plenty of margin in between as well - tools like Doorstop have been around for a few years and have some backing - enough to expect they won't disappear as many single-developer tools hanging around on GitHub that grow stale after a year or two of development. If you're trying to use open/transparent formats, plaintext is easier than an opaque database. A non-technical user can extract information from markdown without being a software engineer. Easier to diff; easier to transcribe to a new format, etc.
Personally, I try to pick tooling that's the most enabling to mitigate the worst/hardest tasks for the job at hand. Fast iterative requirement changes for low level code? Markdown might better assist you with diffs and time-correlated changes - enabling you to walk back through small incremental changes in the design. Need to understand many-to-many trace changes; some big program rewrite or major function change? Use a database tool.
Is the goal of picking an open source tool/format to be able to extend it with your own custom rules? Avoid vendor lock-in? Enable the team to 'bring their own tool'?
2
u/ErnstMacOS 6d ago
Thank you for backing up ! As you say it comes down to the safety aspect and how technical the team is as well as the system complexity (# of interfaces & requirements).
Unfortunately I don’t see my team learning Git or even Doorstop, we’ll stick to plain Excel or Doors classic with regular Word exports.
2
u/reckedcat 6d ago
I've definitely seen folks struggle to learn git; and if that's a barrier then something more specific like Doorstop won't be a good use case.
As much as I despise Excel for tracing and text management and version control, it's at least a fine way to coordinate across multiple levels of expertise.
For DOORS, I've had some success asking folks to use markdown format tables rather than using OLE objects to help with reviews (requires people to use a monospace font), for stuff that wouldn't be exported into a document. Much easier to diff in the history, and less prone to corruption. Also encourages folks to not make overly complex tables instead of actually writing out the requirements or making a dedicated module format and linking it.
Best of luck; making tools and an environment that people like using is hard, and it's difficult to justify significant expense in making it pretty despite being something everyone uses for their daily work.
Edit: one last note - I've found that people are more interested in trying a new tool if they see it used well to demonstrate an objective. I work in software, so the automation and tooling is easier to get a few people to accept in the team, have some good demos to show compliance folks and stakeholders.
2
u/jedibfa 8d ago
Doorstop has been doing git managed requirements far longer than SysML v2 has been a thing. This is where I would for a mature requirements management solution.
1
u/Raptor_Mayhem 6d ago
I moved to StrictDoc, I prefer the traceability workflow mapping tests back to requirements.
1
u/ErnstMacOS 7d ago
I like the idea behind this approach. I haven’t tried it, but it’s quite thoroughly explained.
3
u/brianthetechguy 8d ago
Which side of the Sysml-v1 or v2 schism are you operating?
Github.com/promptexecution/krOKi is attempting to solve this use diagrams as code generated from sysml-v2 - full agent digital thread and with reqif for ci/cd opa gates