📖 docs: migrate Quick Start to using Markdown admonitions

[orangecms]

This gets rid of redundancies from the additional headlines in the custom HTML, increases the density on the screen, and uses pure Markdown as defined by mdBook.

via #5457

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: orangecms
Once this PR has been reviewed and has the lgtm label, please assign camilamacedo86 for approval. For more information see the Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

Hi @orangecms. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

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-sigs/prow repository.

[camilamacedo86]

Hi @orangecms,

Thanks for taking a look at this.

However, I don’t think we should make this change.

The current structure provides a much better experience for readers and end users. When I’m reading documentation and I see a clear H1 title, I can immediately understand what the section is about and decide whether it’s relevant, or skip it if it isn’t.

With the proposed change (example below), the title/context becomes less obvious and it forces readers to scan more text just to figure out whether the section applies to them.

For example:

With the change: I have to read through more content to understand if it’s relevant.

With the current format: I can quickly skip sections I don’t care about (e.g., if I’m not using a specific feature like “Master channel” or I don’t need autocomplete).

Given that this would change the overall documentation structure/syntax and would require re-reviewing the rendered output across the docs to ensure it’s actually better for readers, I think we should only do it if there’s a strong, clearly justified benefit.

Comparing the two, the proposed layout is less reader-friendly: it reduces scannability and forces readers to read more before they can tell whether a section is relevant to their use case.

Therefore, IMO we should not move with this change.

/hold

Thanks!

[camilamacedo86]

@orangecms

Can we use TIP, Warning with the subtitles ? Could we solve the H1--H4 with class and js?
Or would that cause the same problem for anyone using an accessibility tool ?

[orangecms]

@orangecms

Can we use TIP, Warning with the subtitles ?

No, they are just blocks with an extra icon, label and color.

Could we solve the H1--H4 with class and js?
Or would that cause the same problem for anyone using an accessibility tool ?

I have already replied to this question in the other PR; maybe I don't understand the idea.

[camilamacedo86]

Hi @orangecms,

Please see: ( I added images based on the changes to clarify)
#5459 (review)

My point is simple:

• If everything is only TIP, I must read all the content to know if it is relevant.
• With the current format, I only read the note when it applies to me (for example, when using master, which is not common).

Because this is a rare case, keeping it clearly labeled helps users quickly decide whether to read or skip it.

Does that make sense?

[orangecms]

Hi @orangecms,

Please see: ( I added images based on the changes to clarify) #5459 (review)

My point is simple:

• If everything is only TIP, I must read all the content to know if it is relevant.

Why? Tip means it's not necessarily relevant. There are 4 other kinds of admonitions. It's not only tip.

• With the current format, I only read the note when it applies to me (for example, when using master, which is not common).

With the suggested format, I read the full note if the text in bold applies to me, same thing.

Because this is a rare case, keeping it clearly labeled helps users quickly decide whether to read or skip it.

The 5 kinds of admonitions are clear labels?

[orangecms]

The last screenshot in #5459 (review) shows how the different admonitions help:
The first extra info, previously not clear whether it was less relevant or essential, is now an important hint.

[camilamacedo86]

The last screenshot in #5459 (review) shows how the different admonitions help:
The first extra info, previously not clear whether it was less relevant or essential, is now an important hint.

That is not important at all. Unless you are looking to know what version are compatible,
If the person is ONLY looking quick start to understand how that works should completed skip
The IMPORTANT will make the person read and bring confusion for new users.

Why? Tip means it's not necessarily relevant. There are 4 other kinds of admonitions. It's not only tip.

Because the info ONLY matter is I am using the Master branch.
I should NOT need to read that if I am not doing so
Reade that If I am not using the master branch is not helpful at all.

[camilamacedo86]

Hi @orangecms,

Thanks for raising this and taking a look.

I’m OK with any solution as long as it preserves the outcome we need today and avoids regressions or new issues.

For me, that means:

• Don’t force people to read irrelevant information. We still need headers for the callout/box so readers can quickly decide whether it applies to them.
• Don’t make the UX worse. The current experience works well because it’s skimmable and optional.

I think it would help if you could review the docs and try the tool yourself. The boxes are used in many places specifically as “only read this if it’s relevant to you,” and that pattern supports different personas and situations.

For example, readers might be:

• Completely new to Kubebuilder (new to Kubernetes/operators overall).
• A current Kubebuilder user trying to learn how to do a specific thing.
• Already familiar with Kubernetes/operators, but new to Kubebuilder and more interested in how the tool works than the broader concepts.
• Not using Kubebuilder at all, but still benefiting from the docs because they rely on controller-runtime / controller-gen, which they use in their own project.

If we keep those personas in mind, the “optional but clearly labeled” boxes (with headers) are important to avoid overwhelming people while still providing the right info when needed.

Thanks!