Improve content of the projects documentation#1210
Conversation
andreniggemann
left a comment
andreniggemann
left a comment
There was a problem hiding this comment.
Updating our documentation is definitely necessary, so thanks for approaching that topic.
I am a fan of replacing pictures with diagrams as code, but I am not sure mermaid is really suited to these large more complicated diagrams.
We would have to see if that works out.
| %% Module A | ||
| subgraph M1["Module A"] | ||
| direction LR | ||
| ModCfgA["Module Configuration"] | ||
| ModCtrlA["Module Controller<br>(Lifecycle + DI)"] | ||
| FacA["Facade A<br>(public API boundary)"] | ||
| CompA["Component(s) A<br>(internal implementation)"] | ||
| PlugA["Plugins A<br>(module-specific extensions)"] | ||
| RepoA["Repository A"] | ||
|
|
||
| ModCtrlA --> ModCfgA | ||
| ModCtrlA --> FacA | ||
| ModCtrlA --> CompA | ||
| FacA --> CompA | ||
| PlugA -. "extends" .-> CompA | ||
| CompA --> RepoA | ||
| end | ||
|
|
||
| %% Module B | ||
| subgraph M2["Module B"] | ||
| direction RL | ||
| ModCfgB["Module Configuration"] | ||
| ModCtrlB["Module Controller<br>(Lifecycle + DI)"] | ||
| FacB["Facade B<br>(public API boundary)"] | ||
| CompB["Component(s) B<br>(internal implementation)"] | ||
| PlugB["Plugins B<br>(module-specific extensions)"] | ||
| RepoB["Repository B"] | ||
|
|
||
| ModCtrlB --> ModCfgB | ||
| ModCtrlB --> FacB | ||
| ModCtrlB --> CompB | ||
| FacB --> CompB | ||
| PlugB -. "extends" .-> CompB | ||
| CompB --> RepoB | ||
| end | ||
|
|
||
| %% Module C | ||
| subgraph M3["Module C"] | ||
| direction RL | ||
| ModCfgC["Module Configuration"] | ||
| ModCtrlC["Module Controller<br>(Lifecycle + DI)"] | ||
| FacC["Facade C<br>(public API boundary)"] | ||
| CompC["Component(s) C<br>(internal implementation)"] | ||
|
|
||
| ModCtrlC --> ModCfgC | ||
| ModCtrlC --> FacC | ||
| ModCtrlC --> CompC | ||
| FacC --> CompC | ||
| end |
There was a problem hiding this comment.
I think the layout may get nicer, when adding another subgraph for all modules, although it's likely impossible to get the perfect layout with mermaid
There was a problem hiding this comment.
Damn, after quite some time experimenting I found this thread/answer
mermaid-js/mermaid#2509 (comment)
Apparently I followed many other people and encountered the most upvoted open issue of all time in mermaid... A fix wa done in march but not released yet. Maybe I'll just have to wait a bit longer 😅
| subgraph Core["MORYX Core"] | ||
| direction RL | ||
| Runtime(["Runtime / Host Infrastructure"]) | ||
| GDI(["Global DI Container<br>(app-wide composition)"]) |
There was a problem hiding this comment.
That's not part of MORYX anymore, right? We just use the Asp.Net Core provided global container
There was a problem hiding this comment.
Right, that is what I wanted to refer to, tried to make it clearer.
| %% Framework Core | ||
| subgraph Core["MORYX Core"] | ||
| direction RL | ||
| Runtime(["Runtime / Host Infrastructure"]) |
There was a problem hiding this comment.
What is part of this runtime & infra? On the spot I can only think of the things listed separately and the commandcenter.
If it is just the commandcenter, I would replace this point, but perhaps you had something else in mind.
There was a problem hiding this comment.
Na you are right, the runtime is actually the content below. I replaced it with Communication and Launcher, which I think should rather be considered there
There was a problem hiding this comment.
I am a fan of replacing pictures with diagrams as code, but I am not sure mermaid is really suited to these large more complicated diagrams.
The textually described diagrams should not lose comprehensibility. We have put a lot of effort into drawing state charts that only became readable and understandable through manual drawing. The now changed diagrams are a good example of how readability is lost. Mermaid is really cool, however readability and customizability are often lacking. We can also continue to draw them manually and place a draw.io XML file alongside them so they can be edited.
Is there a possibility to have a better format for the mermaid diagrams? Maybe split then into separate ones? Even on a big screen this is not readable and the layout is irritating.
Our images before were much better undastandable
- Replace high-level architecture images with mermaid graphs - Move reverse proxy instructions to tutorial section - Extens tutorials toc - Improve detailed architecture diagrams with more information and transform to mermaid - Improve architecture guidelines with coherent write-downs of architecture concepts
1nf0rmagician
force-pushed
the
feature/improved-docs
branch
from
0a7cf0d to
ab5a069
Compare
|
I'm quite happy with the new version, aside from the fact that the mermaid-bug mentioned above still makes the detailed diagram hard to read. @dbeuchler, @andreniggemann as seen in the architecture guideline document we had moved the components and endpoints guidelines into the home repository. I'm unsure what exactly would be the best place for these documents but having them separated in two repositories seems not the best approach to me. |
3 participants
Summary