[HN Gopher] Better Architecture Diagrams for Agile Teams: action...
___________________________________________________________________
Better Architecture Diagrams for Agile Teams: actionable tips and
lessons
Author : sebportebois
Score : 71 points
Date : 2021-03-27 13:30 UTC (9 hours ago)
(HTM) web link (sportebois.medium.com)
(TXT) w3m dump (sportebois.medium.com)
| rubyist5eva wrote:
| 10 years in the industry and i've never needed any diagrams other
| than the ones that my IDE can automatically generate from the
| code and configuration itself. Anything else is an exercise in
| futility and serves only control-freak managers.
| alixanderwang wrote:
| I'm curious, which IDE and/or plugins? Do you have an example
| of one generated?
| ramoz wrote:
| Im also curious. Im currently having to put together a large
| system design document together and am struggling to find any
| solid automation tools.
|
| The most productive tool I've found is:
| https://github.com/terraform-docs/terraform-docs
|
| Otherwise there is a lot of cloud, K8s, and then
| microservices + app design (typescript)
|
| Decent:
|
| https://github.com/bafolts/tplant
|
| https://github.com/TypeStrong/typedoc
| bo0tzz wrote:
| IntelliJ IDEA can generate diagrams of e.g. call chains or
| class inheritance structures:
| https://www.jetbrains.com/help/idea/class-diagram.html
| BlargMcLarg wrote:
| I wonder if this is a natural problem of the code not being a 1
| on 1 reflection of the proposed model (or a superset which
| includes the proposed model), as well negligence in not syncing
| them up when something changes, which isn't a problem with code
| (just generate it again).
|
| Often, the thing worse than no mental model, is an inconsistent
| mental model sending you in the wrong direction.
| stevesimmons wrote:
| Or when each person has a different mental model, but assumes
| the others share theirs.
| nonameiguess wrote:
| Not sure if you're only ever worked alone, but there's an awful
| lot of value to teams in being able to collectively review
| designs before committing to them, which you can't do if you
| have to code everything up just to generate the design. There's
| also the fact that, in a lot of enterprise and government
| environments, a design needs to be approved before you can
| implement it, so you need a way of expressing a design that
| doesn't require you to implement it first. This isn't approval
| by managers, but by the customers and owners of the environment
| you're going to be installing software into.
|
| Of course, once you have an implementation, documenting the as-
| built configuration using automated tools that generate from
| your actual code and runtime system is the way to go.
| haswell wrote:
| This is an indicator that you have either worked on systems
| that were not very complex, or work in an environment where
| cross-team collaboration is not necessary.
|
| I won't question your claim about your personal need, but if
| you believe such diagrams only serve control freak managers,
| you are closing your mind to the many other possible reasons
| that diagrams need to exist.
|
| This is anecdotal (so is your claim), but I have aphantasia - I
| cannot see with my mind. Diagrams are one of the _only_ ways I
| can reason about some things that I cannot otherwise visualize
| in my head.
|
| People communicate, conceptualize and learn in different ways,
| and that has nothing to do with control-freak managers.
| neolog wrote:
| Which diagramming tools have you found most useful?
| odipar wrote:
| Yed has been serving me for almost 15 years.
|
| I think yed's layout algo's are the best in the industry.
| Also, the extensibility is great (even in the free
| versions).
| vishnugupta wrote:
| > Diagrams are one of the only ways I can reason about some
| things that I cannot otherwise visualize in my head
|
| It's very similar with me.
|
| When I'm grasping a new concept I spontaneously get a pen and
| paper and start drawing block diagrams to visual
| cause/effects, sequence of events/actions etc. Also when I'm
| trying to recall a concept, I have to draw a block diagram.
|
| Same when I'm explaining it to someone. I have to draw,
| otherwise I lose my chain of thought within a couple of
| sentences.
| alixanderwang wrote:
| > This is why you want to limit the amount of information to
| process to the most relevant ones, to make the most relevant
| thing easy to transfer.
|
| This is the limitation of a single image diagram. Anything worth
| diagramming has some complexity; which means you have to remove
| critical info or risk it becoming confusingly messy.
|
| > A widespread mistake is to mix abstraction levels inside a
| diagram. This really increases the cognitive load.
|
| This is one of the core ideas behind https://terrastruct.com [0].
| Split complex diagrams into digestible pieces, via levels of
| abstraction.
|
| [0] full disclosure, i made it out of frustration at current
| diagramming tools.
| didibus wrote:
| Looks nice, but I can't imagine having the time to document all
| layers like that or the entire sequence flow in an animated
| way.
| spockz wrote:
| I've long played with this idea. I would like to draw at the
| most detailed level and then let the tool generate the
| different levels of abstractions for me.
| alixanderwang wrote:
| Yeah we're working on reducing the time it takes to generate.
| Eg hooking up to databases to get schemas, source code for
| dependency graphs, using text to minimally express.
|
| But, I'll say that I think however long it takes, diagrams
| used for documentation is looked at much more than the author
| will have spent on it, and the benefits of having a mental
| model be clearly shared makes it worth a lot of effort.
| splittingTimes wrote:
| My mental model always formed much more around what kind of data
| flows and interactions happen between components.
|
| As a big fan of Domain Driven Design I found "domain
| storytelling" a useful technique when adapted to software
| systems.
|
| With these diagrams it was much easier to convey complex systems
| and their temporal couplings. Especially to higher Management as
| they can actually "read" how the sequence of events flow.
|
| Try it out and see if it can be another tool on your belt.
|
| ===
|
| https://domainstorytelling.org
| sebportebois wrote:
| Tips, useful guidelines, and ways to reason about architecture
| diagrams to help friends create better ones.
| motohagiography wrote:
| This is valuable, with the addition that the quality of
| architectural thinking could be elevated in most of the
| organizations I've been in if before they put marker to
| whiteboard if they adopted the principle of symmetry.
|
| If you don't start with symmetry, you lose meaning because you
| are representing relationships with a basic inconsistency. I've
| sat in meetings with very senior architects who say, "I'm not an
| artist, but here's my thinking," and then go on to ramble and
| sound out their own parenthetical ideas while everyone is too
| polite or embarrassed to interrupt.
|
| Start with dots and lines that make simple polygons or trees, or
| multigraphs. Use solid lines for direct relationships, and dotted
| ones for abstractions and conditionals, and arrows for the
| direction when you know it. Literally every single visual idea
| you are expressing reduces to a graph, and starting with symmetry
| in your drawing provides free clarity about the relationships
| between ideas.
|
| Arguably, maybe you don't want that clarity of symmetry because
| you want others to feel like it's not decided and they can use
| the uncertainty of your foggy thinking to contribute their
| interpretations, and the difference between collaboration
| diagrams and explanatory ones is probably in this, but as a boss
| of mine said to me once, "I don't care what you do, so long as it
| looks like you did it on purpose."
| wcarss wrote:
| What is "the principle of symmetry" with regard to software
| architecture diagrams?
|
| I've never heard of it and the word "symmetry" has so many
| contexts that googling it didn't turn up anything meaningfully
| related.
| etxm wrote:
| Good read. I've always enjoyed using C4, it's nice to have
| consistent notation across diagrams. Another decent tool is
| C4Builder [1] if you like PlantUML. It's based on Docsify.
|
| > Each connection should have a label.
|
| It's amazing to me how often you see diagrams without labels on
| connections.
|
| [lambda] -> [s3]
|
| "Lambda arrows s3?" Is it reading, writing? Creating buckets?
| Managing the ACL? That arrow between two really common components
| leaves a LOT to the imagination.
|
| [1] https://adrianvlupu.github.io/C4-Builder
| spockz wrote:
| Anecdotally, I had a professor who would ask what that arrow
| without label meant and would not process any further data
| until all edges were labelled.
| richie5um wrote:
| I love the book 'Back of the Napkin'. He talks about identifying
| what you are trying to present, and marrying that to the diagram
| you draw. I've used those approaches many times in tech/product
| descriptions.
| markmanx wrote:
| Architecture diagrams should be easy to read and easy to
| maintain. This is exactly why I'm building https://isoflow.io
| odipar wrote:
| I want more formal architecture diagrams: how would they look
| like?
|
| I also want to know whether my architecture diagram is any good?
|
| Is my diagram too detailed, too abstract? Are there any objective
| measures, or is it all heuristics?
|
| That said, 'loose' architecture diagrams can help you convey an
| approach, idea or direction. A strict formalism might kill the
| take-away message.
| splittingTimes wrote:
| As mentioned below, C4 is a nice way to do it.
|
| Other then that, as the article mentions, it all depends on the
| audience and their background/knowledge level. Why not gather
| Feedback from those your diagrams are intended for?
|
| ===
|
| https://c4model.com/
___________________________________________________________________
(page generated 2021-03-27 23:01 UTC)