4 ms·

Having spent fair amount of time on inf.architectural position, I’d really love these tools to also adapt some sort of markup. Sequencediagram.org being perfect

by larodi 3y ago

Having spent fair amount of time on inf.architectural position, I’d really love these tools to also adapt some sort of markup. Sequencediagram.org being perfect example (and others alike) where it takes seconds to put a diagram that otherwise takes hours to prepare. Sadly I know of no standard and lightweight markup for E/R modelling… Mermaid is good for flowcharts, but we still lack reasonably good one for BPMN and enterprise diagrams. (BPMN.io is great but lacks its own lang)

nfm 3y ago
DBML (https://dbml.dbdiagram.io/docs/ https://dbml.dbdiagram.io/docs/) is the only thing I've seen in this space.
- rizky05 3y ago
  [dead]
- larodi 3y ago
  This seems cool, I should give it a try. Whenever thousands of entities fall within scope, one really dreams of useful too to explain things quickly.
deleted 3y ago
[deleted]
bastih 3y ago
What about plantuml - covers a fair bit of ground!
greggyb 3y ago
I have found that diagrams tend not to be worth their effort for data models and ERDs. I spend far too much time either: - working in a visual designer that slows me down Or - fighting the layout engine of a markup language and image compiler with lots of directives to try to get the diagram to lay out anywhere close to reasonably. The most valuable information, to me, is the table schema and the collection of relationships. Toward this end, I use a markdown table of three columns, (Field, Type, Attributes) and a code block with my own shorthand per below: Table[field] -1:N- Table2[field2] Detail[HeaderId] -N:1- Header[Id] All text, no generated pictures. If I need to generate from DDL, that's pretty straightforward. But I can also mock up new designs at typing speed. Diffs are incredibly readable. If I need to make pictures for someone else, I iterate design in a markdown file and then once it's good I will spend the time required to make a picture based off the text. I must admit, I start to question why the pictures are necessary.
- bloopernova 3y ago
  Yeah, the developer experience (DevEx) around diagrams is still really poor, despite some sterling efforts by folks behind Mermaid, PlantUML, D2, etc etc. I want something that will use (text based, tree-sitter diffable, and git stored) architecture diagrams as its source of truth. Then compare those diagrams with actual code, and give us meaningful/useful divergence metrics. And from the source of truth, apply style transforms to display in different ways. D2 can do something like that last bit, with its different layout engines. It feels like we already have the information available: we have (terraform) code that produces infrastructure, and (nodejs) code that produces applications. So how can take that structural information and turn it into something useful? I kind of like the idea of a ML model that gives you some standard views of your diagrams, then asks you which bits are useful, and which bits you want to hide/discard from the final output. Going back and forth with that a bit would produce a JSON file that tells the transform engine what to display. I don't know if an LLM can be prompted to do something like that, but a model-assisted workflow might be useful. I also want to be able to compare before and after architectural decisions. Or compare the infrastructure and application patterns against industry best practices. Plus being able to automatically spit out updated, accurate diagrams for leadership would be great.
- SoftTalker 3y ago
  > I start to question why the pictures are necessary I think I agree. My habit is to keep DDL in version control, one file per database object. If I'm interested in a table, column, or its relationships, I can grep for names, look at the files and see the datatypes, foreign keys, etc. I can also by grepping find any stored procedure or function that references a table or column because the code for those is in version control also. I've tried diagrams and while they are convenient at a fairly high level they can't really show you everything and become unweildy if they try. I've found them of such limited benefit that I just work with text/code. I might make a simple diagram if I have to present/talk about a change.
- larodi 3y ago
  The pictures are necessary when: 1) you do a brainstorming. doing it the visual way is much slower than the markup way. personally done it dozens if not hundreds of times with seq.diagrams. actually started donating to this guy who created sequencediagram.org, he saved me hours 2) you need to communicate chunks of the design with non-technical personnel such as business analysts and folks who have no clue about normal forms, outer joins, relational or hybrid designs, etc. they understand much better with visual assistance, which is in essence - suggestopedic approach (https://en.wikipedia.org/wiki/Suggestopedia https://en.wikipedia.org/wiki/Suggestopedia). and you know what - they never admit their lack of fundamental knowledge, which is even worse than not explaining the matter at all. bpmn and seq.diagrams work very well here, and of course - all 1910s flowchars should be forbidden. 3) when there's a large volume of intertwined entities. you just can't convince me that a graph is better represented as series of relational-algebra-alike texts, and not a planar image of it. try to imagine what the Northwind educational DB looks like as text ... and how you teach/explain to s.o. to walk it. https://support.microsoft.com/en-us/office/northwind-database-diagram-cd422d47-e4e3-4819-8100-cdae6aaa0857 https://support.microsoft.com/en-us/office/northwind-databas...
kevlened 3y ago
Mermaid can also be used for enterprise relationship diagrams: https://mermaid.js.org/syntax/entityRelationshipDiagram.html https://mermaid.js.org/syntax/entityRelationshipDiagram.html

by larodi 3y ago

nfm 3y ago

DBML (https://dbml.dbdiagram.io/docs/ https://dbml.dbdiagram.io/docs/) is the only thing I've seen in this space.

rizky05 3y ago
[dead]
larodi 3y ago
This seems cool, I should give it a try. Whenever thousands of entities fall within scope, one really dreams of useful too to explain things quickly.

deleted 3y ago

[deleted]

bastih 3y ago

What about plantuml - covers a fair bit of ground!

greggyb 3y ago

I have found that diagrams tend not to be worth their effort for data models and ERDs. I spend far too much time either: - working in a visual designer that slows me down Or - fighting the layout engine of a markup language and image compiler with lots of directives to try to get the diagram to lay out anywhere close to reasonably. The most valuable information, to me, is the table schema and the collection of relationships. Toward this end, I use a markdown table of three columns, (Field, Type, Attributes) and a code block with my own shorthand per below: Table[field] -1:N- Table2[field2] Detail[HeaderId] -N:1- Header[Id] All text, no generated pictures. If I need to generate from DDL, that's pretty straightforward. But I can also mock up new designs at typing speed. Diffs are incredibly readable. If I need to make pictures for someone else, I iterate design in a markdown file and then once it's good I will spend the time required to make a picture based off the text. I must admit, I start to question why the pictures are necessary.

bloopernova 3y ago
Yeah, the developer experience (DevEx) around diagrams is still really poor, despite some sterling efforts by folks behind Mermaid, PlantUML, D2, etc etc. I want something that will use (text based, tree-sitter diffable, and git stored) architecture diagrams as its source of truth. Then compare those diagrams with actual code, and give us meaningful/useful divergence metrics. And from the source of truth, apply style transforms to display in different ways. D2 can do something like that last bit, with its different layout engines. It feels like we already have the information available: we have (terraform) code that produces infrastructure, and (nodejs) code that produces applications. So how can take that structural information and turn it into something useful? I kind of like the idea of a ML model that gives you some standard views of your diagrams, then asks you which bits are useful, and which bits you want to hide/discard from the final output. Going back and forth with that a bit would produce a JSON file that tells the transform engine what to display. I don't know if an LLM can be prompted to do something like that, but a model-assisted workflow might be useful. I also want to be able to compare before and after architectural decisions. Or compare the infrastructure and application patterns against industry best practices. Plus being able to automatically spit out updated, accurate diagrams for leadership would be great.
SoftTalker 3y ago
> I start to question why the pictures are necessary I think I agree. My habit is to keep DDL in version control, one file per database object. If I'm interested in a table, column, or its relationships, I can grep for names, look at the files and see the datatypes, foreign keys, etc. I can also by grepping find any stored procedure or function that references a table or column because the code for those is in version control also. I've tried diagrams and while they are convenient at a fairly high level they can't really show you everything and become unweildy if they try. I've found them of such limited benefit that I just work with text/code. I might make a simple diagram if I have to present/talk about a change.
larodi 3y ago
The pictures are necessary when: 1) you do a brainstorming. doing it the visual way is much slower than the markup way. personally done it dozens if not hundreds of times with seq.diagrams. actually started donating to this guy who created sequencediagram.org, he saved me hours 2) you need to communicate chunks of the design with non-technical personnel such as business analysts and folks who have no clue about normal forms, outer joins, relational or hybrid designs, etc. they understand much better with visual assistance, which is in essence - suggestopedic approach (https://en.wikipedia.org/wiki/Suggestopedia https://en.wikipedia.org/wiki/Suggestopedia). and you know what - they never admit their lack of fundamental knowledge, which is even worse than not explaining the matter at all. bpmn and seq.diagrams work very well here, and of course - all 1910s flowchars should be forbidden. 3) when there's a large volume of intertwined entities. you just can't convince me that a graph is better represented as series of relational-algebra-alike texts, and not a planar image of it. try to imagine what the Northwind educational DB looks like as text ... and how you teach/explain to s.o. to walk it. https://support.microsoft.com/en-us/office/northwind-database-diagram-cd422d47-e4e3-4819-8100-cdae6aaa0857 https://support.microsoft.com/en-us/office/northwind-databas...

kevlened 3y ago

Mermaid can also be used for enterprise relationship diagrams: https://mermaid.js.org/syntax/entityRelationshipDiagram.html https://mermaid.js.org/syntax/entityRelationshipDiagram.html