add mermaid diagrams to kcp concepts #3607
Conversation
kcp-ci-bot
added
release-note-none
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
kcp-ci-bot
added
the
size/L
|
Hi @olamilekan000. Thanks for your PR. I'm waiting for a kcp-dev member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
kcp-ci-bot
added
the
needs-ok-to-test
olamilekan000
force-pushed
the
add-contextual-diagram-to-terminologies
branch
2 times, most recently
from
713016a to
6a76879
Compare
|
/ok-to-test |
kcp-ci-bot
added
ok-to-test
olamilekan000
force-pushed
the
add-contextual-diagram-to-terminologies
branch
from
6a76879 to
06194b8
Compare
| ```mermaid | ||
| graph TB | ||
| Title[Workspace Types = Pre-configured Environments] | ||
| subgraph WorkspaceTypes | ||
| AppType[App Workspace Type<br/>Has: DaaS] | ||
| FunctionType[Function Workspace Type<br/>Has: Knative Functions] | ||
| ManagementType[Management Type<br/>Has: User Management] | ||
| end | ||
| Title --> WorkspaceTypes | ||
| WorkspaceTypes -->|creates| Team1[App Team Workspace<br/>Can deploy apps] | ||
| WorkspaceTypes -->|creates| Team2[Functions Team Workspace<br/>Can create functions] | ||
| WorkspaceTypes -->|creates| Team3[Admin Workspace<br/>Can manage users] | ||
| Team1 --> Dev1[App Developer<br/>Sees app tools only] | ||
| Team2 --> Dev2[Function Developer<br/>Sees function tools only] | ||
| Team3 --> Admin1[Administrator<br/>Sees admin tools only] | ||
| ``` |
There was a problem hiding this comment.
This graph is confusing to me. It uses both the terms "Workspace Type" and then for the third one, it's just "Type". Also the fact that the subgraph of all types_ is "creating" new workspaces sounds wrong to me.
In general this graph gives the impression of a hierarchy or control flow, when nothing shown in the graph really is a hierarchy. The "App Developer Sees app tools only" box does not logically follow the "App Team Workspace Can deploy apps" box like the arrow implies.
I'm not sure a graph here helps understanding the different personas.
There was a problem hiding this comment.
This graph is confusing to me. It uses both the terms "Workspace Type" and then for the third one
This is an oversight on my part. I have made corrections.
...Also the fact that the subgraph of all types_ is "creating" new workspaces sounds wrong to me.
In general this graph gives the impression of a hierarchy or control flow, when nothing shown in the graph really is a hierarchy. The "App Developer Sees app tools only" box does not logically follow the "App Team Workspace Can deploy apps" box like the arrow implies.
I didn't intend to make it look hierarchical. It was just based on my understanding. I can update the diagram
| ```mermaid | ||
| graph TB | ||
| Title[API Exporting/Binding = Sharing Tools Between Workspaces/Logical Clusters] | ||
| subgraph ToolOwner [Infra: Has Unique Tools] | ||
| Infra[Infra Workspace] | ||
| SpecialTool[Special Database API <br/>PostgreSQL Operator] | ||
| APIExport[API Export <br/> I'm sharing my Database tool] | ||
| end | ||
| subgraph ToolUsers [App Teams - Need Tools] | ||
| AppTeam1[App Team 1 Workspace] | ||
| AppTeam2[App Team 2 Workspace] | ||
| APIBinding1[API Binding <br/> I want to use Database tool] | ||
| APIBinding2[API Binding <br/> I want to use Database tool] | ||
| end | ||
| Title --> ToolOwner | ||
| Infra --> SpecialTool | ||
| SpecialTool --> APIExport | ||
| APIExport -->|shares with| APIBinding1 | ||
| APIExport -->|shares with| APIBinding2 | ||
| APIBinding1 --> AppTeam1 | ||
| APIBinding2 --> AppTeam2 | ||
| AppTeam1 --> CanUse1[App Team 1: <br/>can now create PostgreSQL databases] | ||
| AppTeam2 --> CanUse2[App Team 2: <br/>can now create PostgreSQL databases] |
There was a problem hiding this comment.
This graph is even more confusing to me. It shows relations like "the workspace follows/depends on the APIBinding" (?), introduces the "I" persona and talks about "tools" instead of APIs. The usage of a mermaid chart feels very forced to me here.
Also this might be triggering me personally because it reminds me of this banger of a meme an admin friend made over a decade ago:
cc @EX0l0N
There was a problem hiding this comment.
How do you think this can be better presented?
There was a problem hiding this comment.
I could see a sequence diagram that shows the flow from "infra team setting up their service, then their apiexport" and then afterwards the "team discovers api, team binds it, team uses it". Right now the diagram kind of conflates two aspects to me:
- the "fanning out" aspect, where one service team provides a service to many consumers
- the sequence of actions that happen from providing to consuming a service
Squeezing both into the same diagram is hard.
Signed-off-by: olalekan odukoya <[email protected]>
olamilekan000
force-pushed
the
add-contextual-diagram-to-terminologies
branch
from
06194b8 to
1960410
Compare
|
Im just wondering if we should just get shared Canva for Exalidraw and do it there. maintain as much as it's maintainable - it just does its own thing, and it's hard (not impossible, but very hard) to have something clearly explainable using these. @olamilekan000 if I get one, do you want maybe a collab on those? as I feel we need something that users can grasp from first sight. And this is not it :/ |
|
Sorry, diagrams comes just after "naming" as harders problems in IT. |
I am open to a collab. Do you have a canva workspace we can use? or how do we start? @mjudeikis |
sent via DM |
4 participants
Summary
What Type of PR Is This?
/kind documentation
Related Issue(s)
Fixes #
Release Notes