5 ms·

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.

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 6y ago
I'm curious, which IDE and/or plugins? Do you have an example of one generated?
- bo0tzz 6y ago
  IntelliJ IDEA can generate diagrams of e.g. call chains or class inheritance structures: https://www.jetbrains.com/help/idea/class-diagram.html https://www.jetbrains.com/help/idea/class-diagram.html
- ramoz 6y ago
  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 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/bafolts/tplant https://github.com/TypeStrong/typedoc https://github.com/TypeStrong/typedoc
BlargMcLarg 6y ago
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 6y ago
  Or when each person has a different mental model, but assumes the others share theirs.
haswell 6y ago
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 6y ago
  Which diagramming tools have you found most useful?
  - odipar 6y ago
    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 6y ago
  > 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.
nonameiguess 6y ago
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.

alixanderwang 6y ago

I'm curious, which IDE and/or plugins? Do you have an example of one generated?

bo0tzz 6y ago
IntelliJ IDEA can generate diagrams of e.g. call chains or class inheritance structures: https://www.jetbrains.com/help/idea/class-diagram.html https://www.jetbrains.com/help/idea/class-diagram.html
ramoz 6y ago
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 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/bafolts/tplant https://github.com/TypeStrong/typedoc https://github.com/TypeStrong/typedoc

BlargMcLarg 6y ago

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 6y ago
Or when each person has a different mental model, but assumes the others share theirs.

haswell 6y ago

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 6y ago
Which diagramming tools have you found most useful?
- odipar 6y ago
  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 6y ago
> 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.

nonameiguess 6y ago

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.