knative / knative/docs

It is not clear why Eventing optional components are optional

Open
#4,535 4 comments 2 reactions 0 assignees View on GitHub
hacktoberfest kind/bug kind/eventing lifecycle/frozen priority/high
Dominant language
HTML
Stars
5.1k
Forks
1.3k
PR merge metrics
No merged PRs in 30d

Description

Users have been reporting multiple times that their Broker or Channel setup doesn't work because the documentation reports that Broker and Channel layers are optional like in https://github.com/knative/eventing/issues/5944.

Those optional components are required to follow the next steps, so I'm proposing to remove the Optional word in the heading and instead add a sentence explaining why a Broker or Channel layer might be optional and what you can't do without that particular layer.

## Expected Behavior

- There is no confusion

## Steps to Reproduce the Problem

1. Install required components only
1. Follow the create a Broker page: https://knative.dev/docs/eventing/broker/create-mtbroker/

## Additional Info
- https://knative.dev/docs/install/eventing/install-eventing-with-yaml/
- https://knative.dev/docs/install/eventing/install-eventing-with-yaml/#optional-install-a-default-channel-messaging-layer
- https://knative.dev/docs/install/eventing/install-eventing-with-yaml/#optional-install-a-broker-layer

**Install information:**
- Platform (GKE, IKS, AKS, etc.): All
- Knative Version: All

/kind eventing

Contributor guide

Open the contributing guide

Research direction

Start with the installation documentation sections linked in the issue, especially the anchors for the optional default channel messaging layer and broker layer. Review the create-a-Broker page to confirm which next steps depend on each layer. Done means removing the misleading “Optional” wording and adding clear explanations of when each layer is optional and what is unavailable without it.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.