7 ms·

Too complex. Architecture descriptions should make sense to everyone on the project. It should not require you to learn a new design language or notation to use

Too complex. Architecture descriptions should make sense to everyone on the project. It should not require you to learn a new design language or notation to use. Here's an example of a complex system that's easy to get your head around - https://www.wittenburg.co.uk/Design.aspx https://www.wittenburg.co.uk/Design.aspx Unfortunately it won't do much for an architect's ego but, if the same simplistic approach to diagrams is applied to all levels of abstraction, it just may provide a thing all stakeholders can reason about and agree to.

Silhouette 7y ago
Too complex. Architecture descriptions should make sense to everyone on the project. It should not require you to learn a new design language or notation to use. That seems a little strong. We're talking about a potentially complicated system in a technical field. Some standardised notation and terminology could be helpful to keep the visuals concise and unambiguous. I agree that this looks far too complicated, though.
- Spearchucker 7y ago
  UML already provides that, no?
  - Silhouette 7y ago
    Personally I find UML (in its full, standardised form) is still a lot more complicated than is normally necessary too, but it does include versions of several useful ideas. I have often seen a group of developers discussing something and then someone sketches a simple diagram showing entities and relationships, transitions of a finite state machine, or message-passing similar to what UML would call a sequence or communication diagram. However, in my entire career, I have never seen anyone actually draw out fully annotated UML diagrams using the official notation, nor any instance of some of the numerous diagram types UML specifies. And that includes working at places where everyone had been given UML training!
    - simon_brown 7y ago
      I've seen a number of organisations where everybody has been given UML training, and mandated to use a specific UML tool. In reality though, everybody is just abusing UML class diagrams as a way to draw ad hoc "boxes and lines" diagrams instead! :-)
    - Spearchucker 7y ago
      UML in its full, standardized form is an anti-pattern. There are many useful things in it though. Sequence and activity diagrams, for example.
- prepend 7y ago
  I’ve tried and used uml for 20 years. It’s hard to learn and a different way of thinking for many staff. I see a pattern of the business analyst / product owner /non-tech lead hiring someone to make uml for ver. That abstraction costs money and time and creates confusion. So I think it’s not a worthwhile investment. The non-techs can’t create or edit and typically can’t read. The techs don’t use it for what they are creating. I’d rather spend time on docs in the actual system components or teaching non-techs enough to read autogenerated docs or walk through code that actually is the system. Then couple that with block diagrams written on whiteboards or powerpoints or whatever. If you get to the point you need notations it’s too complicated and point them to the appropriate source. This isn’t easy. But I think it’s easier than pretending that both sides learning an artificial middle language (uml, etc). Because construction analogies are stereotypical if you are building a building. A big, expensive skyscraper. If your construction workers speak English and your financiers and architects speak French. I think you’re better off investing in hiring some people who speak both languages than in making them both speak German to work on blueprints.
splittingTimes 7y ago
Looks a bit like domain story telling: https://domainstorytelling.org/ https://domainstorytelling.org/ I really like the approach of event modeling recently: https://eventmodeling.org/ https://eventmodeling.org/
- Spearchucker 7y ago
  It's a conceptual design which is exactly like domain story telling.
  - ptrott2017 7y ago
    And domain story telling is like a constrained form of Chekland's rich pictures (which had some good ideas along with a chunk of cruft).
simon_brown 7y ago
As some background, the rationale behind creating the C4 model was to create software architecture diagrams that would be easy for anybody on the project team to understand. The example diagram you linked to is fairly typical of what most teams seem to do today unfortunately, and exhibits the following problems: ambiguously named boxes, unclear responsibilities, unexplained symbols, ambiguous relationships between elements, no key/legend, unclear abstractions, etc. To solve these problems, you do need some sort of common language. Switching to UML potentially solves many of these problems, but teams don't want to do this for various reasons. As noted on the website, the C4 model is an abstraction-first approach (with only 4 levels to learn), although the simple notational tips do aid comprehension.
- Spearchucker 7y ago
  This I agree with, other than prescribing n levels - many projects don't need more than 1, most only need 3 (conceptual, logical, physical). Note that people in the protection (life insurance) industry will see no ambiguity in this diagram. Note also that this diagram is contained in a Vision/Scope document that provides disambiguation (each box is described), responsibilities (and all stakeholders) defined, and all abstractions. Haven't anonymized that document so it's not online. Obviously no one on the team works alone, so it's made clear to all. Largely based on the Microsoft Solutions Framework from many years ago because it's still the best tool in this space. And by god after 20 years as an architect and before that 14 as a developer I've seen my share. I respect the effort brought to bear here, but there are existing solutions and frameworks out there, from the terrible (6 Sigma or EDS' BCL Framework) to the excellent (MSF 3, parts of the UML).
  - blub 7y ago
    I like C4 because the diagrams are easy to understand irrespective of the industry and those diagrams cover an abstraction span that's impossible to cover through one diagram. I didn't get the feeling that it has to be 4 diagrams and I pick and choose myself. I get it that the example you gave works for your project, but if I took that and transplanted it into mine I'd expect a lot of questions at least about the relationships (arrows) and probably also about the responsibilities of the components (boxes). Having a textual description of the above certainly helps and should be done, but people tend to focus on the diagrams and ignore the text in my experience.
blub 7y ago
Your example is less clear to me compared to the C4 method. It's missing descriptions for relationships for one. Secondly, a single diagram can't tell the whole story.
hackerm0nkey 7y ago
The C4 model doesn't seem to mandate any particular notation, it's merely lines and boxes and you can use whatever notation you prefer. "The C4 model doesn't prescribe any particular notation. A simple notation that works well on whiteboards, paper, sticky notes, index cards and a variety of diagraming tools is as follows." Curious to know what makes you think it's too complex? What am I missing?
xienze 7y ago
> Too complex. Disagree. It might not come across so great in written form but I watched this person give a presentation on this model and it was one of the best I’d ever seen. Probably the most logical way to explain a complex system. And then he rolled out the library he had written that could generate these diagrams automagically from Spring code... mind blown.

Silhouette 7y ago

Too complex. Architecture descriptions should make sense to everyone on the project. It should not require you to learn a new design language or notation to use. That seems a little strong. We're talking about a potentially complicated system in a technical field. Some standardised notation and terminology could be helpful to keep the visuals concise and unambiguous. I agree that this looks far too complicated, though.

Spearchucker 7y ago
UML already provides that, no?
- Silhouette 7y ago
  Personally I find UML (in its full, standardised form) is still a lot more complicated than is normally necessary too, but it does include versions of several useful ideas. I have often seen a group of developers discussing something and then someone sketches a simple diagram showing entities and relationships, transitions of a finite state machine, or message-passing similar to what UML would call a sequence or communication diagram. However, in my entire career, I have never seen anyone actually draw out fully annotated UML diagrams using the official notation, nor any instance of some of the numerous diagram types UML specifies. And that includes working at places where everyone had been given UML training!
  - simon_brown 7y ago
    I've seen a number of organisations where everybody has been given UML training, and mandated to use a specific UML tool. In reality though, everybody is just abusing UML class diagrams as a way to draw ad hoc "boxes and lines" diagrams instead! :-)
  - Spearchucker 7y ago
    UML in its full, standardized form is an anti-pattern. There are many useful things in it though. Sequence and activity diagrams, for example.
prepend 7y ago
I’ve tried and used uml for 20 years. It’s hard to learn and a different way of thinking for many staff. I see a pattern of the business analyst / product owner /non-tech lead hiring someone to make uml for ver. That abstraction costs money and time and creates confusion. So I think it’s not a worthwhile investment. The non-techs can’t create or edit and typically can’t read. The techs don’t use it for what they are creating. I’d rather spend time on docs in the actual system components or teaching non-techs enough to read autogenerated docs or walk through code that actually is the system. Then couple that with block diagrams written on whiteboards or powerpoints or whatever. If you get to the point you need notations it’s too complicated and point them to the appropriate source. This isn’t easy. But I think it’s easier than pretending that both sides learning an artificial middle language (uml, etc). Because construction analogies are stereotypical if you are building a building. A big, expensive skyscraper. If your construction workers speak English and your financiers and architects speak French. I think you’re better off investing in hiring some people who speak both languages than in making them both speak German to work on blueprints.

splittingTimes 7y ago

Looks a bit like domain story telling: https://domainstorytelling.org/ https://domainstorytelling.org/ I really like the approach of event modeling recently: https://eventmodeling.org/ https://eventmodeling.org/

Spearchucker 7y ago
It's a conceptual design which is exactly like domain story telling.
- ptrott2017 7y ago
  And domain story telling is like a constrained form of Chekland's rich pictures (which had some good ideas along with a chunk of cruft).

simon_brown 7y ago

As some background, the rationale behind creating the C4 model was to create software architecture diagrams that would be easy for anybody on the project team to understand. The example diagram you linked to is fairly typical of what most teams seem to do today unfortunately, and exhibits the following problems: ambiguously named boxes, unclear responsibilities, unexplained symbols, ambiguous relationships between elements, no key/legend, unclear abstractions, etc. To solve these problems, you do need some sort of common language. Switching to UML potentially solves many of these problems, but teams don't want to do this for various reasons. As noted on the website, the C4 model is an abstraction-first approach (with only 4 levels to learn), although the simple notational tips do aid comprehension.

Spearchucker 7y ago
This I agree with, other than prescribing n levels - many projects don't need more than 1, most only need 3 (conceptual, logical, physical). Note that people in the protection (life insurance) industry will see no ambiguity in this diagram. Note also that this diagram is contained in a Vision/Scope document that provides disambiguation (each box is described), responsibilities (and all stakeholders) defined, and all abstractions. Haven't anonymized that document so it's not online. Obviously no one on the team works alone, so it's made clear to all. Largely based on the Microsoft Solutions Framework from many years ago because it's still the best tool in this space. And by god after 20 years as an architect and before that 14 as a developer I've seen my share. I respect the effort brought to bear here, but there are existing solutions and frameworks out there, from the terrible (6 Sigma or EDS' BCL Framework) to the excellent (MSF 3, parts of the UML).
- blub 7y ago
  I like C4 because the diagrams are easy to understand irrespective of the industry and those diagrams cover an abstraction span that's impossible to cover through one diagram. I didn't get the feeling that it has to be 4 diagrams and I pick and choose myself. I get it that the example you gave works for your project, but if I took that and transplanted it into mine I'd expect a lot of questions at least about the relationships (arrows) and probably also about the responsibilities of the components (boxes). Having a textual description of the above certainly helps and should be done, but people tend to focus on the diagrams and ignore the text in my experience.

blub 7y ago

Your example is less clear to me compared to the C4 method. It's missing descriptions for relationships for one. Secondly, a single diagram can't tell the whole story.

hackerm0nkey 7y ago

The C4 model doesn't seem to mandate any particular notation, it's merely lines and boxes and you can use whatever notation you prefer. "The C4 model doesn't prescribe any particular notation. A simple notation that works well on whiteboards, paper, sticky notes, index cards and a variety of diagraming tools is as follows." Curious to know what makes you think it's too complex? What am I missing?

xienze 7y ago

> Too complex. Disagree. It might not come across so great in written form but I watched this person give a presentation on this model and it was one of the best I’d ever seen. Probably the most logical way to explain a complex system. And then he rolled out the library he had written that could generate these diagrams automagically from Spring code... mind blown.