Overview

Well named pages and headings help users quickly find the right information.
Consistent naming aids in scanning the table of contents, and accurate names
make search more effective.

Audit page and heading titles for consistency and accuracy.

Audience: All

Type: All

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://github.com/knative/docs/
• https://knative.dev/docs/client/
• https://knative.dev/docs/getting-started/tutorial/
• https://knative.dev/docs/serving/
• https://knative.dev/docs/eventing/

Suggested changes:

• Remove "About" from titles:
  • "About Installing Knative" > "Installing Knative"
  • "About Eventing Features" > "Eventing Features"
  • and so on.
• Rename "Tutorial" to "Tutorials" (there is more than one tutorial here).
• Make verb tense consistent in procedure titles. Use "-ing" verbs to title tasks
  and processes (thiis is already done in the majority of cases!):
  • [Configure Broker defaults] > "Configuring Broker defaults"
  • [Install Knative using quickstart] > "Installing Knative using quickstart"
  • and so on.
• In [Serving] and [Eventing], rename "Developer Topics" and
  "Admin Topics" to "Developer Tasks" and "Admin Tasks" to cue readers.
• Retitle this page:
  [Knative Eventing - The Event-driven application platform for Kubernetes]
  to "Eventing".
• Rename "Knative CLI" to "CLI tools".
• Make TOC titles agree with page titles. Some examples (not a complete list):
  • Change "Install the Knative CLI" in the TOC to match the page title:
    [Installing the Knative CLI].
  • Change the page title: [Metrics] to match "Configuring metrics" in the TOC.
  • Change "About Apache Kafka Broker" in the TOC to match the page title:
    [Knative Broker for Apache Kafka].
• Rename "About" in the landing page banner to something less misleading: "Why
  Knative?", "Testimonials and Case Studies", or "Endorsements".