I would like to know why the last section was dropped. Other parts have been removed with no explanation either, such as the admonitions with notes/warnings in the current live docs.

I removed the last section because on the one hand, we already have a section about certificates, on the other hand, if you want to have a dedicated section about certificates, why just write about Let'sEncrypt? I feel like with K8s, there is more to it, especially when you consider certManager.

Any reason for dropping the usage of example admonitions, especially collapsible ones? Only one remains at the end.

I found it odd that you'd need to unfold them, because this is the content everyone is there for...

some content needs to be broken apart into smaller paragraphs.

Why do you figure? I must say I disagree.

I would like to have feedback from another k8s user/contributor, but presently the current docs seem more approachable.

I think that with the current docs, before you're able to work with it, you'd need to expand 4 admonitions, and you do not have a clear structure. But this is just my PoV.

you'd need to expand 4 admonitions

I am not familiar with the yaml configs being shared, if all the snippets are relevant to the user you can collapse under 1 admonition for example with each clearly labeled, or if this information will always be relevant to the reader of this page, avoid any collapsing.

When there is optional configs, it often made more sense imo to reduce visual noise by collapsing it by default, a reader would scan through the document or ToC sidebar and get the information they want.

I can understand if that workflow differs for others. I personally prefer heavy pages to not be as overwhelming to someone seeking guidance by using progressive disclosure UX (a few extra clicks at most vs overloading someone with everything all at once which usually isn't as well received, especially if only a portion is actually relevant to focus on).

If the intention is to copy these configs as files, we can "import" them into the docs, they'll be rendered as they do currently, but we can additionally link to them on github to copy/paste from a clone of the repo. I believe I have instructions for that on my WIP documentation of the doc features (progress stalled due to other priorities). Would that be helpful?

you do not have a clear structure

At least with the collapsed snippets, for someone familiar with k8s which seems to be the expectation here, the structure of them seemed clear that they were k8s related config and the names matched the kind metadata?

Your updates are helpful with the added context between them, but I think we could improve that a little, perhaps with some subheadings and not collapsing the description for each part into a single hefty paragraph? They're minor improvements compared to the value of your contribution, but they help make the content more easier to follow 😅

I removed the last section because on the one hand, we already have a section about certificates, on the other hand, if you want to have a dedicated section about certificates, why just write about Let'sEncrypt?

I don't mind it being removed, so long as we're not losing any value it may provide. If that information isn't of value or is already covered elsewhere no worries, otherwise we should perhaps migrate it somewhere more appropriate.

LetsEncrypt is popular enough that I don't mind it if it's helpful/relevant (we don't cover k8s anywhere else but this page right?). Removing it because it's only covering LetsEncrypt isn't valid, if anyone else wants to contribute alternatives that'd be welcomed, but it shouldn't be mandated if the information would be helpful.

Do you think it would be better suited and of value to the TLS docs page?

I found it odd that you'd need to unfold them, because this is the content everyone is there for...

I can't really comment for this docs page as I am not familiar with what and how much of the information presented is relevant to all viewers on that page.

As stated earlier, there is value in collapsible admonitions when appropriate imo.

Regular admonitions still help with the layout of the page content and conveying the info at a glance. I would personally prefer using them but unless anyone is going to weigh in, either way is fine. The information documented is more important, presentation is complimentary to that.

Why do you figure? I must say I disagree.

I find:

A Service is required for getting the traffic to the pod itself. The service is somewhat crucial. Its configuration determines whether the original IP from the sender will be kept. More about this further down below. The configuration you're seeing does keep the original IP, but you will not be able to scale this way. We have chosen to go this route in this case because we think most K8s users will only want to have one instance anyway, and users that need high availability know how to do it anyways. You will want to have your load-balancer give this service an external, routable IP address.

to be worse UX vs:

Service

A Service is required for getting the traffic to the pod itself. The service is somewhat crucial. Its configuration determines whether the original IP from the sender will be kept. More about this further down below.

The configuration you're seeing does keep the original IP, but you will not be able to scale this way. We have chosen to go this route in this case because we think most K8s users will only want to have one instance anyway, and users that need high availability know how to do it anyways.

You will want to have your load-balancer give this service an external, routable IP address.

which is easier to digest, especially in the context of the whole document.

There's already some verbosity from the writing style we could trim, but just giving the content some more breathing space really helps (at least for me it's heavily appreciated, imagine my verbose responses compacted into just a few paragraphs..).

If I have some k8s familiarity and have a setup already or looking back at these docs to reference something, is it possible that I might want to quickly lookup one of these manifests as reference? With the subheading it'll be added to the ToC sidebar under the mainfests heading level, and it'll be easier to scroll through the document and locate (if not using the ToC).

About the TLS / certificates topic: Kube-Lego is deprecated, and should not be used in new deployments anymore. You'd want to use CertManager. However, there are many possibilities. That's why I'd leave this section (or mention it in the TLS section seperately).

I have added more subsections to structure the document a bit more. This way, one can jump to the appropriate manifest file in an instant. I would however very much try to avoid putting the configuration files in admonitions that one has to unfold. With recent versions of MkDocs (which we are using), there is a dedicated copy button in the top right hand corner one can use to copy the code as a whole :)

I have also split the description for the service.

I will test this ASAP, but I have to figure out how solve a problem with Cilium in my cluster first. I will mark this as ready for review as soon as I know my mail server setup works.

@polarathene Sorry for dismissing your review again. Because of #2113 I realised I forgot to update the caps list :)

@radicand Have you had time to get a look at the updates?:) If you don't have the time, I think it's not a big deal, I'd just need to know :D

@radicand Have you had time to get a look at the updates?:) If you don't have the time, I think it's not a big deal, I'd just need to know :D

Starting now...

I'm done with my review, feel free to take or leave any of my points :)

Alright. Thank you @radicand for your suggestions :D

@polarathene I have enabled auto-merge. If you think this PR is fine as is, it should get merged when you approve it :)

@polarathene You have already approved this PR a thousand times. Therefore, I'm going to assume you're fine with it and I'm beating you to the punch (a strange English phrase) with merging this PR so you don't have to approve it again :D

Tried my best, but only reviews from reviewers with write-access count when it comes to unblocking this PR. I re-enabled auto-merging. The next you accept @polarathene, this PR will be merged :)

Documentation preview for this PR is ready! 🎉

Built with commit: 1f638ee