CNCF Tech Doc Recommendations: Umbrella Issue

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.

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.

• https://github.com/knative/docs/issues/6302

✏️ Rename pages

Audit page and heading titles for consistency and accuracy.

• 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.

• 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.

• https://github.com/knative/docs/issues/6305

✏️ Reorganization issues

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

• 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.

• 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.

• https://github.com/knative/docs/issues/6308

✏️ Add a glossary

Add a glossary of terms to the technical documentation.

• 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].

• https://github.com/knative/docs/issues/6311

✏️ Improve troubleshooting

Improve Knative troubleshooting instructions by adding explanations.

• https://github.com/knative/docs/issues/6312

✏️ Fill out the Eventing API

Improve the explanations in the Eventing API.

• 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.

• 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.

• 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.

• https://github.com/knative/docs/issues/6316