CNCF Tech Doc Recommendations: Umbrella Issue

## FEATURE REQUEST: ☂ CNCF Tech Doc Recommendations

### Overview

This is a checklist for the CNCF technical documentation analysis and implementation plan. It should be updated as sub-issues are added, completed, or otherwise modified.

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/0015-knative/

The CNCF Knative documentation effort is tracked in the CNCF Tech Docs repo:
https://github.com/cncf/techdocs/issues/315

## 🗞️ Sub-issues

This is a list of issues representing the recommended work on the Knative website(s) and technical documentation.

### ✏️ Separate technical documentation from the project page

The Knative project [landing page] redirects to the doc page:
`https://knative.dev/docs/`.

It's helpful to users if there's a clear separation between technical
documentation and other information. The technical documentation is goal-driven
and should be factual, specific, and purposeful.

Separate the technical documentation from the project landing page.

- [x] https://github.com/knative/docs/issues/6302

### ✏️ Rename pages

Audit page and heading titles for consistency and accuracy.

- [x] https://github.com/knative/docs/issues/6303

### ✏️ Update technical overview

Write a conceptual overview of Knative where the "Concepts"
section is in the current documentation, but be much more comprehensive.

- [x] https://github.com/knative/docs/issues/6304

### ✏️ Update Installation to better orient users

Add "roadmap" information to orient readers in the Installation section of the
documentation.

- [x] https://github.com/knative/docs/issues/6305

### ✏️ Reorganization issues

This issue suggests several changes to the documentation's organization to
improve usability and consistency.

- [x] https://github.com/knative/docs/issues/6306

### ✏️ Document the kn CLI on the site

The `kn` CLI documentation is maintained in the
[/knative/kn] repo, except for the install instructions, which are on the doc
site.

Consolidate the `kn` CLI documentation so that it's maintained in one place.

- [x] https://github.com/knative/docs/issues/6307

### ✏️ Revise the Security and threat disclosure page

The [Knative Security and Disclosure Information] page has some misleading and
confusing elements. Rewrite the introduction to this page so that it's clear
what procedures and information are available.

- [x] https://github.com/knative/docs/issues/6308

### ✏️ Add a glossary

Add a glossary of terms to the technical documentation.

- [x] https://github.com/knative/docs/issues/6309

### ✏️ Review graphics

Review the graphics on the site to make sure they meet these criteria:

- Does the graphic enhance understanding? Does it add information that can't be
conveyed in a few words?
- Is the graphic placed in context by the surrounding text?
- Does the graphic's size and aspect ratio enable proper placement and text flow
on a variety of screens sizes?
- Is the graphic maintainable: Will it require frequent updating for
localization, software updates, or interface changes?

- [ ] https://github.com/knative/docs/issues/6310

### ✏️ Edit for conformance to style guide

Edit the website for conformance to the [Knative style guide].

- [x] https://github.com/knative/docs/issues/6311

### ✏️ Improve troubleshooting

Improve Knative troubleshooting instructions by adding explanations.

- [x] https://github.com/knative/docs/issues/6312

### ✏️ Fill out the Eventing API

Improve the explanations in the Eventing API.

- [x] https://github.com/knative/docs/issues/6313

### ✏️ Write a Getting Started page

Write a getting started page to orient new users, with meta information
about what to expect and where to go on the documentation site.

- [x] https://github.com/knative/docs/issues/6314

### ✏️ Make install downloads findable

Move and relabel the download file section so that the files are easy to find.

- [x] https://github.com/knative/docs/issues/6315

### ✏️ Truncate search results

Displaying the entire page text of each search result hinders users' ability to find their result.

Configure the Search to truncate results after 100 characters or so.

- [x] https://github.com/knative/docs/issues/6316

Start with the analysis in cncf/techdocs/analyses/0015-knative/ and the linked CNCF Tech Docs issue 315, then review the unchecked graphics sub-issue 6310. The issue names no files or tests; completion is described only as carrying out the recommendations and keeping this checklist current.

Written by the indexing model from the issue text.