Are there any tools that will go from a whiteboard sketch to a format like Mermaid, PlantUML or even SVG (as boxes, lines and text)? I assumed that with the AI revolution /s there would be such a thing but I haven’t found it…
Architecture diagrams enable better conversations
111–120 of 141 posts
Re: Architecture diagrams enable better conversations
#112I find architecture diagrams particularly useful for interviews of high-level candidates. I'll structure the first half as an informal conversation where I pick up some technical work they've done and get them to talk about it in depth. The second half is usually explaining the 10kft and 1kft arhitectural overview of our product. However, I find that pre-prepared architecture diagrams are not that helpful in this cas…
I think there is something to the fact that drawing the diagram in front of someone - the performance of drawing - communicates something in itself. The way you place boxes initially to set out spatial relationships. The direction in which you draw the arrows. The speed at which you draw them - clearly and deliberately, or swiftly and as an aside. The things you drew and then had to erase and redraw bigger. The way you're able to augment the diagram as you go to elaborate on or clarify your audience's points of confusion. All of that is part of what you're communicating when you draw a diagram in front of someone.
None of that is part of what you capture in a static diagram in an architecture document.
That's one reason why I suspect that the diagrams in documentation shouldn't necessarily look like the ones you draw in a collaborative session.
Re: Architecture diagrams enable better conversations
#113I find architecture diagrams particularly useful for interviews of high-level candidates. I'll structure the first half as an informal conversation where I pick up some technical work they've done and get them to talk about it in depth. The second half is usually explaining the 10kft and 1kft arhitectural overview of our product. However, I find that pre-prepared architecture diagrams are not that helpful in this cas…
> A good grasp of overall architecture allows you to produce your own heuristic for how to navigate the code, where to look for problems, build internal models of where things might be going wrong, etc.
This is the benfit of using a framework, if you are building different projects. Learn one architecture intimately, and you save a lot of headroom. You can also hire people familiar with the framework, who have built this intuition already, even though they have never seen your codebase before.
Re: Architecture diagrams enable better conversations
#114I should probably learn C4, however, I’ve been having a great time just drawing arrows between squares with draw.io, labelling things as I see fit, without any real ruleset. This is how I generally design any larger feature and present it to the team. It seems to be well received, and being able to reference the initial architecture diagram when I want to remember how some particular system works is extremely useful. I think these diagrams risk becoming impenetrable and unpleasant to work with if they become too beset with rules and arcane visual language (see UML).
Re: Architecture diagrams enable better conversations
#115I'll go on a limb and share a counter-point for why I struggle with diagrams: it's anecdotal but might help someone else accept that diagrams are not for everyone. As someone with aphantasia, they don't help me memorize relationships, so to get them into my working memory, I have to translate a diagram into bullet points: it's so much easier just to start with those bullet points of what components we've got, what th…
I think I am a highly visual person but I don't like diagrams either. There is a somewhat interesting historical irony around the development of architecture as in how this word is meant in IT and what a real architect does. The famous gang of four design patterns book got it's name from a book by the architect Christopher Alexander called a Pattern Language. This book advocates using textual description for user requirements like "I want to be able to drink my coffee in the morning and watch the sun rise". It sort of constrains the layout of the house but it still leaves a lot of room to move things around.
Re: Architecture diagrams enable better conversations
#116If C4 is new to you too, I recommend their intro video: https://www.youtube.com/watch?v=x2-rSnhpw0g.
It feels like a very light ruleset over what we would do naturally when explaining a system to another engineer. That's great.
Some of the ideas that stood out were:
1. Allow flexibility in the notation (shapes and color) as long as the abstractions are good.
2. When drawing arrows, make them unidirectional to show the main intent.
3. Hide details to express the main story (@ 27min in the video)
4. Don't just give names to components. Give short descriptions too.
5. Don't document the lowest levels. Code is better here.
Re: Architecture diagrams enable better conversations
#117[flagged]
Re: Architecture diagrams enable better conversations
#118I’ve had some interesting results using GPT4 to generate mermaid diagrams from descriptions of my architecture or processes.
Plus, the output being code, it’s easy to fine tune when the inevitable mistake creeps in every once in a while.
It’s funny. I have never documented anything so thoroughly. It was just too time-consuming. Now I do. In part because I know there will be a diagram to complement it and improve the likelihood any of it will prove useful to someone at some point.
But also because keeping said documentation and diagrams up to date will be easier.
Re: Architecture diagrams enable better conversations
#119I've been using https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/ . It's very easy to embed a C4 diagram into a markdown document. The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (fo…
Structurizr looks popular but I don't love needing to learn yet another DSL. Does there exist a way to describe things in an existing language with a library?
To use the example on their website, I would like something like this in JS:
let { Component, Container, Diagram, Person } = import 'c4'
let user = new Person('User')
let system = new Container('Software System')
let webapp = new Component('Web Application')
let database = new Component('Web Application')
system.contains(webapp)
system.contains(database)
user.uses(webapp).via('Uses')
webapp.uses(database).via('Reads from and writes to')
export new Digram()
.title('Software System')
.theme('default')
.shows([user, system])
.type('container')
- Python: https://github.com/nielsvanspauwen/pystructurizr
- C#: https://github.com/8T4/c4sharp
Don't see one for JS though. Smells like an opportunity for someone.
Re: Architecture diagrams enable better conversations
#120I'll go on a limb and share a counter-point for why I struggle with diagrams: it's anecdotal but might help someone else accept that diagrams are not for everyone. As someone with aphantasia, they don't help me memorize relationships, so to get them into my working memory, I have to translate a diagram into bullet points: it's so much easier just to start with those bullet points of what components we've got, what th…
Interestingly, as someone with aphantasia they're absolutely critical for me - because I'm not able to visualise the relationships without a diagram in from of me to "see" (This was the same for me with more abstract undergraduate maths, too). Given just the bullet points I find it hard to conceptualise the relationships between them without quickly forgetting the points I'm not directly loooking at.
I echo your point that diagrams are not the solution for everyone (and that a multimodal representation of relationships is clearly best), I just find it fascinating how even with something as specific as aphantasia, there is still so much variability as to how it's experienced.