Fill out the Eventing API #6313
Description
Overview
The Eventing API contains no explanatory or introductory text, and many
descriptions of functions and fields are missing, rudimentary, or tautological.
Improve the explanations in the Eventing API.
Audience: Developers
Type: Reference
Context
This issue tracks recommended changes resulting from an analysis of the Knative
documentation commissioned by CNCF. The analysis and supporting documents are
here: https://github.com/cncf/techdocs/tree/main/analyses under 0015-knative.
Possible Implementation
Related material in the current doc:
Suggested changes:
Add a brief introduction to the Eventing API, explaining what the API is for,
what kind of API it is (REST, presumably), where to find it, and how to include
it.
Provide semantic information in descriptions about endpoints and fields. Do not
only restate information available from the element name. For example, the
BackoffPolicyType option has no explanation. It would be helpful to know what
the backoff is for: "Backoff is the delay before trying to reconnect after
failing to deliver an event" (or whatever). The description of its first value,
"exponential", reads: "Exponential backoff policy". More helpful would provide
more information: "Retry after an exponentially increasing number of seconds (1,
2, 4, 8, and so on)".