Improve troubleshooting

[dwelsch-esi]

Overview

Troubleshooting instructions are too terse in Knative. They provide commands for
diagnosing issues, but do not explain a procedure.

Improve troubleshooting by adding explanations.

Audience: All

Type: Instructional

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:

• https://knative.dev/docs/install/troubleshooting/
• https://knative.dev/docs/bookstore/page-0.5/environment-setup/#troubleshooting
• https://knative.dev/docs/install/installing-backstage-plugins/#troubleshooting
• https://knative.dev/docs/serving/troubleshooting/debugging-application-issues/
• https://knative.dev/docs/bookstore/page-1/send-review-comment-to-broker/#step-2-create-broker
• https://knative.dev/docs/bookstore/page-2/sentiment-analysis-service-for-bookstore-reviews/#prerequisite-1-install-knative-func-cli

Suggested changes:

Two possible approaches:

1. Expand each troubleshooting step to explain what the step is trying to
   diagnose. (Many of the current troubleshooting steps are no more than "use this
   command to diagnose ..."). Make sure that there are links to each step from the
   procedure where the issue can be encountered.
2. Consolidate all the troubleshooting procedures to a single troubleshooting
   guide, organized by component. Again, provide links to the relevant points in
   the guide from each procedure.
   Exception: The end-to-end tutorial example has a lot of troubleshooting
   information. As is the case currently, it should have its own troubleshooting
   guide or guides.