6 ms·

Has anyone a good idea about how to document high level architecture. I want something to document a huge web of interlinked pieces. E.g. this application is

Has anyone a good idea about how to document high level architecture. I want something to document a huge web of interlinked pieces. E.g. this application is linked to this URL, which has been deployed on that server, connects to a database there, which has DNS aliases X Y Z, etc... Bonus points if it can scan our environment, and warn me when something has changed. Some details: Our company is still firmly architected around the 'pets, not cattle' server philosophy, we have tons of teams each owning a small piece of the puzzle, people come and go. Hence,every time something changes, we spend a lot of time on architecture archeology to find back our own application. There is some work done around the 4+1 view, but its all in word documents, mostly declared holy and locked down so nobody is allowed to update them or even look at them once written, and no 2 people agree about what 4+1 actually means. https://en.wikipedia.org/wiki/4%2B1_architectural_view_model https://en.wikipedia.org/wiki/4%2B1_architectural_view_model

rho4 5y ago
I prefer a diagram on a company wiki that contains only text boxes and connections. Accessible and editable by anyone in the browser (we use draw.io plugin for confluence). I accept that these diagrams will always be out-of-date and therefore try to keep text and details to a minimum. I think of it more as a pointer for where to "dig up" a piece of the system or who to ask, to use your metaphor.
craig0990 5y ago
I've actually just tried something similar for work (we'll see how it goes). Take Material for MkDocs with the "mermaid2" and "plantuml-markdown" plugins, a custom plugin to inline SVG diagrams [1], and "mike" for versioning. This gets us a Git repo where anyone can draw and contribute diagrams with either Mermaid, PlantUML, or Draw.io diagrams embedded in SVG. Hosted in GitLab Pages for access control. All three diagram formats support hyperlinks in their outputs, so we're aiming for a clickable, "zoom-able" adaptation of the C4 Model [2]. It's a bit fiddly to get going, but quite nice and easy to work with afterwards, provided individuals can commit time to updating the diagrams. In principle, GitLab supports PlantUML with extra config, and SVG embeds, but in practice we can't yet commit to updating our self-hosted GitLab, and the SVG embed is aggressively filtered - so Draw.io embeds often show up blank. MkDocs solves the "make it pretty, browseable, and searchable" aspect. Git and "mike" solve the "what was the original design again?" aspect. I'm tempted to write the approach up, but I broke my blog - perhaps I should rebuild it with Material for MkDocs :) The Material for MkDocs Insiders program gets you nice extras (mermaid support built-in, stay-on-same-page across "mike" versions, and more) [3] [1] https://pypi.org/project/mkdocs-plugin-inline-svg/ https://pypi.org/project/mkdocs-plugin-inline-svg/ [2] https://c4model.com/ https://c4model.com/ [3] https://squidfunk.github.io/mkdocs-material/insiders/ https://squidfunk.github.io/mkdocs-material/insiders/ (edit: typos)
- hyperman1 5y ago
  Thanks. This is an alternative vision compared with what I am doing, but it seems better. Especially the C4 model as basic philosophy, and then the supporting technology. Pleas blog about this, it is very interesting to me. Just to be sure: this is what you mean with Mike? https://github.com/jimporter/mike https://github.com/jimporter/mike
  - craig0990 5y ago
    Yep, that's the one - the versioning was more important to me than it might be to others (even internally). mike was a bit confusing to set up in CI since it re-commits the build back to a branch (imagine the loops you could get yourself into) but the output is nice. We're not strict about C4 (we actually created an alternative-but-similar flow incidentally) - but C4 to me is a nice diagrammatic principle of "Don't Repeat Yourself" - draw a box, label it, and link to that system's diagram instead. I could go on for pages / hours :D I'm a bit over-passionate about documentation. Email's in my profile, FWIW.
- chrisweekly 5y ago
  Thanks, this is similar to what I have started to work on. Note GitLab supports a Kroki integration, which is a powerful way to enable "all the things" wrt diagramming libs.
hyperpallium2 5y ago
High level architecture documentation is the most-needed and least-done. Some ideas: - one piece of (longish) sample code that uses each stage. It can also be an end-to-end test (not unit) and so forced in sync - "Design Patterns" - unpopular now, but the whole idea was common idioms so everyone can tell what you're doing. - very separate modules, with good names; interacting via simple APIs, with good names. Choose these names from outside the implementation, as if by someone who doesn't know it. The names will tell you what it is and what it does.
- kordlessagain 5y ago
  Shell scripts!
cjlovett 5y ago
You can use DGML with Visual Studio, then export that as SVG and even animate the SVG like this https://microsoft.github.io/coyote/concepts/actors/state-machine-demo/ https://microsoft.github.io/coyote/concepts/actors/state-mac...
AYBABTME 5y ago
I use PlantUML. I ignore the UML bit and just use it for code-based diagramming.
- cratermoon 5y ago
  This is a good answer. Ditch the tools graphical tools that store diagrams in a proprietary or image-centric format. Diagrams as text that can be effectively managed alongside code in git or whatever version control system you used

rho4 5y ago

I prefer a diagram on a company wiki that contains only text boxes and connections. Accessible and editable by anyone in the browser (we use draw.io plugin for confluence). I accept that these diagrams will always be out-of-date and therefore try to keep text and details to a minimum. I think of it more as a pointer for where to "dig up" a piece of the system or who to ask, to use your metaphor.

craig0990 5y ago

I've actually just tried something similar for work (we'll see how it goes). Take Material for MkDocs with the "mermaid2" and "plantuml-markdown" plugins, a custom plugin to inline SVG diagrams [1], and "mike" for versioning. This gets us a Git repo where anyone can draw and contribute diagrams with either Mermaid, PlantUML, or Draw.io diagrams embedded in SVG. Hosted in GitLab Pages for access control. All three diagram formats support hyperlinks in their outputs, so we're aiming for a clickable, "zoom-able" adaptation of the C4 Model [2]. It's a bit fiddly to get going, but quite nice and easy to work with afterwards, provided individuals can commit time to updating the diagrams. In principle, GitLab supports PlantUML with extra config, and SVG embeds, but in practice we can't yet commit to updating our self-hosted GitLab, and the SVG embed is aggressively filtered - so Draw.io embeds often show up blank. MkDocs solves the "make it pretty, browseable, and searchable" aspect. Git and "mike" solve the "what was the original design again?" aspect. I'm tempted to write the approach up, but I broke my blog - perhaps I should rebuild it with Material for MkDocs :) The Material for MkDocs Insiders program gets you nice extras (mermaid support built-in, stay-on-same-page across "mike" versions, and more) [3] [1] https://pypi.org/project/mkdocs-plugin-inline-svg/ https://pypi.org/project/mkdocs-plugin-inline-svg/ [2] https://c4model.com/ https://c4model.com/ [3] https://squidfunk.github.io/mkdocs-material/insiders/ https://squidfunk.github.io/mkdocs-material/insiders/ (edit: typos)

hyperman1 5y ago
Thanks. This is an alternative vision compared with what I am doing, but it seems better. Especially the C4 model as basic philosophy, and then the supporting technology. Pleas blog about this, it is very interesting to me. Just to be sure: this is what you mean with Mike? https://github.com/jimporter/mike https://github.com/jimporter/mike
- craig0990 5y ago
  Yep, that's the one - the versioning was more important to me than it might be to others (even internally). mike was a bit confusing to set up in CI since it re-commits the build back to a branch (imagine the loops you could get yourself into) but the output is nice. We're not strict about C4 (we actually created an alternative-but-similar flow incidentally) - but C4 to me is a nice diagrammatic principle of "Don't Repeat Yourself" - draw a box, label it, and link to that system's diagram instead. I could go on for pages / hours :D I'm a bit over-passionate about documentation. Email's in my profile, FWIW.
chrisweekly 5y ago
Thanks, this is similar to what I have started to work on. Note GitLab supports a Kroki integration, which is a powerful way to enable "all the things" wrt diagramming libs.

hyperpallium2 5y ago

High level architecture documentation is the most-needed and least-done. Some ideas: - one piece of (longish) sample code that uses each stage. It can also be an end-to-end test (not unit) and so forced in sync - "Design Patterns" - unpopular now, but the whole idea was common idioms so everyone can tell what you're doing. - very separate modules, with good names; interacting via simple APIs, with good names. Choose these names from outside the implementation, as if by someone who doesn't know it. The names will tell you what it is and what it does.

kordlessagain 5y ago
Shell scripts!

cjlovett 5y ago

You can use DGML with Visual Studio, then export that as SVG and even animate the SVG like this https://microsoft.github.io/coyote/concepts/actors/state-machine-demo/ https://microsoft.github.io/coyote/concepts/actors/state-mac...

AYBABTME 5y ago

I use PlantUML. I ignore the UML bit and just use it for code-based diagramming.

cratermoon 5y ago
This is a good answer. Ditch the tools graphical tools that store diagrams in a proprietary or image-centric format. Diagrams as text that can be effectively managed alongside code in git or whatever version control system you used