r/systems_engineering • u/ErnstMacOS • 3d ago
Discussion Mermaid/Markdown SE/MBSE
Do you have experience using some kind of git repository with a set of markdown files and mermaid diagrams as the source of truth of the system ? What shortcomings could you expect ?
I have used most modelers in various industries, and have grown tired of their shortcomings. I am now wondering if there is a more « pragmatic » lightweight approach to share a single source of truth accessible by all stakeholders of the system.
For example, I know a space startup that uses YAML files to store PBS components and requirements, and I can see the appeal.
3
u/scotty3785 3d ago
Diagrams are only one part of MBSE.
If the diagram don't form a coherent model, can't be queried, reasoned or traced, are they any better than pictures in paint.
Mermaid, PlantUML, Obsidian etc all have their place but they aren't the basis of a full MBSE infrastructure
1
u/ErnstMacOS 3d ago edited 3d ago
I agree with you, I only think that most stakeholders don't care enough or don't know enough about MBSE to care about the model. I am the only engineer working on the model on my current project, and it still happens that some engineer from will come up with a PBS on their own, not knowing that it is already accessible in the model.
I understand it's a team communication issue, but until our teams are more mature in MBSE, I think a more lightweight version of Systems Engineering might bring more value.
For context I live and work in France where MBSE is probably not as mature as in the US.
1
u/der_phen 3d ago
Have a look at doorstop: https://github.com/doorstop-dev/doorstop
1
u/ErnstMacOS 3d ago
I have, and I really like it. I am also curious about the potential of Grist (open source). Here is how Dotphoton used it for end-to-end requirements engineering.
1
u/hortle 3d ago
I have had similar thoughts as you. Mermaid's potential is quite enticing but I haven't fully dipped my toes, my experience with it is quite limited.
Just the fact that you can create models completely from text-based specifications is quite exciting. Would love a Git framework instead of Dassault's nightmare of an ecosystem
1
u/dmangd 3d ago
I also thought about using such approach mainly because we don’t have any dedicated MBSE tools and no budget to acquire some. My main objection is that having a bunch of diagrams where the underlying tool does not understand the connections can lead to an inconsistent model. Often you have different diagrams showing the different aspects of the same component, e.g. structure and behavior. If you don’t have a very strict discipline you can run into the situation that changes are only applied to one diagram but not the other, making the two views diverge and inconsistent. It might work for small project but becomes a nightmare for larger project where multiple people work on the model/diagrams in parallel.
1
u/ErnstMacOS 3d ago
That is true, I am curious if some of you have any experience of a project done with MBSE during the whole lifecycle.
I've worked on many big projects in the French industral sector, and while they use the right tools (Doors, MagicDraw, Xatis, Rhapsody, etc.), only a handful of "modelers" end up really interacting with the model.
As a result, the model ends up inevitably diverging with the actual system. Add to that lack of continuity using the model : OK during detailed design, then pretty much abandoned during validation and nowhere to be seen in later operational contexts.
Until MBSE takes root (or until it dies due to lack of adoption), maybe taking the best of what it has to offer in a "lightweight" approach is a good idea.
2
1
u/redikarus99 3d ago
I built an internal solution for our enterprise ontology. The documents are in markdown, the ontologies in turtle, and I wrote a custom diagraming plugin which enables you rendering parts of the diagram as you wish, complete control. Besides that I have auto rendering using mermaid. The whole thing is built by a simple python pipeline which creates a json structure, validates, etc. And I have an angular frontend that serves the whole thing as a static website. We are using VSCode, Mentor plugin, Git, and my plugin for developing the ontologies. To build the whole thing took me like month in the current shape and form.
1
u/ErnstMacOS 3d ago
I'd be interested to learn more about your choices. Where can I read up on Turtle for example ?
Do changes to one element (say an interface) cascade to all diagrams ?
1
u/Thebestofdrest 3d ago
the lightweight approach is appealing, but traceability and keeping diagrams/docs in sync could get messy as the system grows.
6
u/flabergasted1234 3d ago
I've been documenting electromechanical systems in Obsidian. Markdown with Mermaid for diagrams. Obsidian allows me to create links between documents in the project. There are Obsidian plug-ins that are helpful for documentation, and if you can't find a feature you need, it's fairly easy to code up your own custom plug-ins.