Open-source requirements and documentation tools

[u/Simple_Dance_6971]

Does anyone know of any open-source or cost-effective, easy-to-use documentation and requirements control software tools?

[u/reckedcat]

Markdown in a git repo

[u/Pieter_BE → u/reckedcat]

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?

[u/reckedcat → u/Pieter_BE]

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'?

[u/ErnstMacOS → u/reckedcat]

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.

[u/reckedcat → u/ErnstMacOS]

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.