Fix reorganization issues 6306 #6506
Conversation
❌ Deploy Preview for knative failed.Built without sensitive environment variables
|
knative-prow
bot
added
the
size/S
| --- | ||
| audience: developer | ||
| components: | ||
| - eventing | ||
| function: reference | ||
| --- | ||
|
|
||
| # Eventing FAQs | ||
|
|
||
| ## What is a Sugar Controller? | ||
|
|
||
| The Sugar Controller is an optional controller which will automatically create and clean up brokers based on the creation/deletion of namespaces and triggers. | ||
| For more information on how to enable and configure the sugar controller, read the [sugar controller documentation](../sugar/README.md). |
There was a problem hiding this comment.
I'd prefer not to remove the FAQ, this was something that was highlighted as something we needed in our docs due from user research. I understand it only has one entry currently - maybe a better fix is to expand it? cc @evankanderson
There was a problem hiding this comment.
Do you have a list of the other FAQs? Generally, FAQs should actually be frequently asked, and I'm not sure that the "Sugar Controller" rises to that level.
There was a problem hiding this comment.
For this, sugar controller was a frequently asked question in KubeCon Chicago (not 100% sure why 🤷 )
I can take a look at expanding the FAQ section, probably next week sometime
There was a problem hiding this comment.
Even just a list of frequently-asked questions without answers could be useful. As-is, the content is a bit lonely.
evankanderson
left a comment
evankanderson
left a comment
There was a problem hiding this comment.
The event mesh change makes sense, though you should add it to the config/redirects.yml file.
I'm happy to remove the "release notes" page, as it wasn't really adding much value.
It sounds like Calum has some plans for the FAQ -- either hold off, or get a list of topics that we can at least incorporate as comments, even if we don't have great answers yet. (And maybe if we write the questions, an LLM can do a first pass on the answers and then we refine it.)
docs/versioned/relnotes/README.md
Outdated
There was a problem hiding this comment.
This document isn't in our navigation (I'm not sure where we'd put it), so it functionally doesn't really exist. If it contained more content than simply links to the GitHub releases page, I'd be more inclined to keep it. My current feeling is that it's not worth it, so we should drop it.
There was a problem hiding this comment.
I suggest we delete this file.
There was a problem hiding this comment.
Deleted this file
docs/versioned/.nav.yml
Outdated
| # Concepts | ||
| ############################################################################### | ||
| - Overview: README.md | ||
| - Quick Start: README.md |
There was a problem hiding this comment.
The "Technical Overview" is an overview, and not a quick start. The quickstart is under the "tutorials" section.
Since that issue was opened, we've changed the homepage text to "Try the tutorial", rather than the somewhat-misleading "Explore Knative":
There was a problem hiding this comment.
Reverted the change and modified Overview to Explore Knative under tutorials
| --- | ||
| audience: developer | ||
| components: | ||
| - eventing | ||
| function: reference | ||
| --- | ||
|
|
||
| # Eventing FAQs | ||
|
|
||
| ## What is a Sugar Controller? | ||
|
|
||
| The Sugar Controller is an optional controller which will automatically create and clean up brokers based on the creation/deletion of namespaces and triggers. | ||
| For more information on how to enable and configure the sugar controller, read the [sugar controller documentation](../sugar/README.md). |
There was a problem hiding this comment.
Do you have a list of the other FAQs? Generally, FAQs should actually be frequently asked, and I'm not sure that the "Sugar Controller" rises to that level.
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: skmahe1077 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 |
| - Observability: | ||
| - Collecting metrics: eventing/observability/metrics/collecting-metrics.md | ||
| - Metrics Reference: eventing/observability/metrics/eventing-metrics.md | ||
| - FAQ: eventing/faq/README.md |
There was a problem hiding this comment.
I think @Cali0707 was requesting that we don't delete this at this time.
Calum, how strongly do you feel about this? Sugar controller might have been a hot topic a few years ago, but is it still frequently asked?
There was a problem hiding this comment.
I still think we should not be deleting this file. In the UX WG call on Wed we spoke about updating and expanding this in the next few weeks, and @Leo6Leo is already looking into finding our research earlier about FAQs new eventing users have. I agree sugar controller is maybe less of a hot topic now, but I don't think that means we should remove it from the FAQs.
There was a problem hiding this comment.
Added the file again
docs/versioned/relnotes/README.md
Outdated
There was a problem hiding this comment.
I suggest we delete this file.
evankanderson
left a comment
evankanderson
left a comment
There was a problem hiding this comment.
One more comment, thanks for doing this (and sorry that versioned documentation is so persnickety).
|
|
||
| The Sugar Controller is an optional controller which will automatically create and clean up brokers based on the creation/deletion of namespaces and triggers. | ||
| For more information on how to enable and configure the sugar controller, read the [sugar controller documentation](../sugar/README.md). | ||
| For more information on how to enable and configure the sugar controller, read the [sugar controller documentation](/docs/eventing/sugar). |
There was a problem hiding this comment.
Don't use absolute links here; they will break for anything other than the current version (e.g. pre-release or v1.21 when that's old will link to "current version" rather than the same version as the source link.
Additionally, mkdocs link checking does not work for absolute links (and the GitHub rendering will also be off).
There was a problem hiding this comment.
Mkdocs also "likes it" when you link to the markdown files, and will adjust the urls on publish as needed.
There was a problem hiding this comment.
Sorry i have copied from the deleted file somehow missed the path and now corrected the link and verified in my local
|
|
3 participants
Fixes #6306
This PR reorganizes and updates documentation pages across the Knative Docs site in line with the recommendations outlined in the referenced issue