knative/docs

It is not clear why Eventing optional components are optional

Open

#4,535 opened on Dec 2, 2021

View on GitHub
 (4 comments) (2 reactions) (0 assignees)HTML (1,202 forks)batch import
hacktoberfestkind/bugkind/eventinglifecycle/frozenpriority/high

Repository metrics

Stars
 (4,320 stars)
PR merge metrics
 (Avg merge 4d 20h) (1 merged PR 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
  2. Follow the create a Broker page: https://knative.dev/docs/eventing/broker/create-mtbroker/

Additional Info

Install information:

  • Platform (GKE, IKS, AKS, etc.): All
  • Knative Version: All

/kind eventing

Contributor guide

Research direction
Review the linked documentation pages and understand which components are truly required for common workflows. Then propose changes to remove 'Optional' from headings and add clarifying sentences.
Tech stack
None
Domain
backendcloud
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
GitKnative basics
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75