search

cert-manager / website

Source code for the cert-manager.io website, including project documentation
https://cert-manager.io
Apache License 2.0
54 stars 337 forks source link

Add overview diagrams for "Requesting Certificates" section #1329

Closed inteon closed 1 year ago

inteon commented 1 year ago

Quick overview diagrams on each of the "Requesting Certificates" pages.

https://deploy-preview-1329--cert-manager-website.netlify.app/docs/usage/

image

https://deploy-preview-1329--cert-manager-website.netlify.app/docs/usage/certificate/

image

https://deploy-preview-1329--cert-manager-website.netlify.app/docs/usage/ingress/

image
netlify[bot] commented 1 year ago

Deploy Preview for cert-manager-website ready!

Name Link
Latest commit 26a8bcbfb8385f62ea48b8043f0b6f1098976dd6
Latest deploy log https://app.netlify.com/sites/cert-manager-website/deploys/65491ef4c810b600089e354d
Deploy Preview https://deploy-preview-1329--cert-manager-website.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

maelvls commented 1 year ago

Nice. The unrelated boxes (CSI driver etc) are now greyed out. It is much less confusing. The diagram now clearly shows a Certificate in the center: that's great because this page is about the Certificate resource.

As a first-time reader of this page, I would probably still skip the diagram entirely because this diagram because it looks confusing:

  1. The top of the page talks about the Certificate and Issuer resources, but the Issuer resource doesn't show on the diagram; that's surprising.
  2. Do I need to create an "Annotated Ingress" to create a Certificate? That's what the diagram alludes to.
  3. Although I know what is an Ingress, what is an "Annotated Ingress"?
  4. Since I didn't know what was an Annotated Ingress, I did ctrl+F but didn't find any reference to "Annotated Ingress".
  5. I know about Istio's Gateway resource, but what is an "Annotated Gateway"?

One way of making it much clearer would be to write a legend to this diagram to explain what the reader should understand from the diagram

inteon commented 1 year ago

Nice. The unrelated boxes (CSI driver etc) are now greyed out. It is much less confusing. The diagram now clearly shows a Certificate in the center: that's great because this page is about the Certificate resource.

As a first-time reader of this page, I would probably still skip the diagram entirely because this diagram because it looks confusing:

  1. The top of the page talks about the Certificate and Issuer resources, but the Issuer resource doesn't show on the diagram; that's surprising.
  2. Do I need to create an "Annotated Ingress" to create a Certificate? That's what the diagram alludes to.
  3. Although I know what is an Ingress, what is an "Annotated Ingress"?
  4. Since I didn't know what was an Annotated Ingress, I did ctrl+F but didn't find any reference to "Annotated Ingress".
  5. I know about Istio's Gateway resource, but what is an "Annotated Gateway"?

One way of making it much clearer would be to write a legend to this diagram to explain what the reader should understand from the diagram

  1. The diagram does not really apply to issuers, each resource references the issuer resource (annotated Ingresses, Certificates, CertificateRequests, ...). So I did not include that to not overwhelm the diagram.

  2. There are multiple ways to create a Certificate resource, I updated the diagram with a set of letters (indicating the different paths/ options) and a legend that explains what the different arrows mean.

3&4&5. On the Ingress and Gateway page, we talk about adding annotations to your ingress resource, so I think this should be clear to the user?

maelvls commented 1 year ago

This is an improvement over the existing page, so let's go with that!

My concerns are:

  1. The grey stuff isn't needed to understand each page. It makes things confusing.
  2. The "a", "b", "c" on the arrows should say the actual action (e.g., "creates").
  3. It's not clear which resources are created by cert-manager, "automated action" doesn't really say that; using a line separation between "created by the user" and "created by cert-manager" would help.
  4. The "Secret" should show on the diagram too since the point is to explain what Kubernetes resources are at play. I would even show the Issuer, but that's less important.

/lgtm /approve

jetstack-bot commented 1 year ago

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: maelvls

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files: - ~~[OWNERS](https://github.com/cert-manager/website/blob/master/OWNERS)~~ [maelvls] Approvers can indicate their approval by writing `/approve` in a comment Approvers can cancel approval by writing `/approve cancel` in a comment