search

kubernetes / website

Kubernetes website and documentation repo:
https://kubernetes.io
Creative Commons Attribution 4.0 International
4.49k stars 14.43k forks source link

Make cluster diagram(s) more comprehensible #36155

Open miyadav opened 2 years ago

miyadav commented 2 years ago

I'd be happy to see a bigger change to the diagram, eg adding a tooltip for each component, or letting you click on (eg) the k-c-m icon to see details of the component. There is room to improve.

This smaller change feels like it's not enough of an improvement though.

_Originally posted by @sftim in https://github.com/kubernetes/website/pull/34841#discussion_r916606830_

k8s-ci-robot commented 2 years ago

@miyadav: The label triage/accepted cannot be applied. Only GitHub organization members can add the label.

In response to [this](https://github.com/kubernetes/website/issues/36155#issuecomment-1221779101): >/triage accepted > Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
miyadav commented 2 years ago

cc @divya-mohan0209 , @sftim .

jihoon-seo commented 2 years ago

Page: https://kubernetes.io/docs/concepts/overview/components/ /kind feature /language en

jihoon-seo commented 2 years ago

/area web-development

sftim commented 2 years ago

/triage accepted

sftim commented 2 years ago

/retitle Make cluster diagram(s) more comprehensible

Santosh1176 commented 2 years ago

Hey, @sftim can I work on this? Please correct me, if I am wrong. This needs some hover effects showing some details about the icon.

sftim commented 2 years ago

I'm open to hearing about different ideas about ways to improve things. Hover effects are just one option - and won't work on touchscreen devices such as phones and tablets.

Another option is to drop the icons and use words instead; in fact, that's what an older version of that diagram did. Or we could use words plus icons, using those symbols more like badges. Or something else I didn't think of.

chrismetz09 commented 2 years ago

My preference is KEEP IT SIMPLE. Just use boxes, lines, arrows and words. IMHO new users can grasp architecture components faster and contributors can create/modify diagrams much easier. Here is a "hack-ish" example contained in the Mermaid live editor of how you could to do this using open-source Mermaid:

Partial example of K8s components diagram using Mermaid

You can click on a node to point to more detailed info. Try it with etcd node in the example. If we think some iconography helps, Mermaid can use fontawesome.

Check out the Diagram Guide for more info on Mermaid. This approach subscribes to the Diagrams-as-code paradigm.

k8s-triage-robot commented 1 year ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

divya-mohan0209 commented 1 year ago

/remove-lifecycle stale

sftim commented 1 year ago

Also see https://github.com/kubernetes/website/issues/39234

devarsh10 commented 1 year ago

Hey @miyadav, I had created a prototype of diagram. Please take look & let me know for any changes. Or should raise a PR.

https://viewer.diagrams.net/index.html?tags=%7B%7D&highlight=0000ff&edit=_blank&layers=1&nav=1&title=cluster-arch.drawio.svg#Uhttps%3A%2F%2Fdrive.google.com%2Fuc%3Fid%3D1ges4a6irOexKsRApwAVjYbZHQgzAt8gR%26export%3Ddownload[](https://viewer.diagrams.net/index.html?tags=%7B%7D&highlight=0000ff&edit=_blank&layers=1&nav=1&title=cluster-arch.drawio.svg#Uhttps%3A%2F%2Fdrive.google.com%2Fuc%3Fid%3D1ges4a6irOexKsRApwAVjYbZHQgzAt8gR%26export%3Ddownload)

Regards.

miyadav commented 1 year ago

Thanks @devarsh10 for looking into it , but the flowchart is conceptually exactly same as the existing diagram so not adding much value , may be you can make a PR to add text-hover / hyperlink on existing diagram . may be @sftim can give you better feedback .

devarsh10 commented 1 year ago

Thanks for your reply. I'll try to improve the existing one. And my prototype consists of hyperlinks.[Hope you noticed].

sftim commented 1 year ago

Using text labels is helpful. I suggest that each person who's making a proposal opens a pull request. You can start with an empty commit and use the PR comments to run a discussion.

That way, we can have conversations between authors and other contributors, with each conversation happening separately (mixing them up may be confusing!)

devarsh10 commented 1 year ago

Okay. So @sftim, may I raise a PR? By adding my prototype's link.

sftim commented 1 year ago

Anyone who follows the code of conduct - basically, be nice to people - is welcome to contribute. You will need to sign the CLA as well - you can do that as an individual or through your employer, whichever is more appropriate.

devarsh10 commented 1 year ago

Hey all, I raised a PR #39389. Please take a look into it. And let me know for some changes to be made.

Regards.

sftim commented 1 year ago

Also see https://github.com/kubernetes/website/issues/39614

k8s-triage-robot commented 8 months ago

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

k8s-triage-robot commented 5 months ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

sftim commented 5 months ago

/triage accepted

not removing stale marker