Review graphics

[dwelsch-esi]

Overview

Graphics should enhance understanding by illustrating concepts and processes. Many graphics on the Knative site detract from, rather than enhance, the usability of documentation.

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?

Review the graphics that are on the site. Remove graphics that don't justify the space they take up. Scale the graphics to a more appropriate size if necessary.

Audience: All

Type: Conceptual

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/concepts/
• https://knative.dev/docs/concepts/eventing-resources/brokers/
• https://knative.dev/docs/getting-started/tutorial/
• https://knative.dev/docs/getting-started/next-steps/
• https://knative.dev/docs/bookstore/page-0/welcome-knative-bookstore-tutorial/
• https://knative.dev/docs/bookstore/disclaimer/
• https://knative.dev/docs/bookstore/* (all bookstore pages)
• https://knative.dev/docs/serving/architecture/
• https://knative.dev/docs/serving/request-flow/
• https://knative.dev/docs/serving/encryption/encryption-overview/

Suggested changes:

• Briefly introduce the system diagram in the [Concepts overview]. This can be a single phrase added to the sentence below the graphic: "The primary Knative Serving resources are Services, Routes, Configurations, and Revisions, as shown in the previous figure:".
• Similarly for other conceptual graphics on the site: Refer to them from the text.

[evankanderson]

/kind documentation /good-first-issue

[knative-prow[bot]]

@evankanderson: This request has been marked as suitable for new contributors.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed by commenting with the /remove-good-first-issue command.

In response to this:

/kind documentation /good-first-issue

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[evankanderson]

We should establish a standard set of icons under https://github.com/knative/docs/tree/main/contribute-to-docs/style-guide; see this thread for more details. A few other highlights:

• Recommend one or two tools for generating documentation images. A lot of the current images are .png from Google Slides (my fault!). I'd recommend .svg documents created by either Inkscape or in-line with Mermaid in markdown source.

[github-actions[bot]]

This issue is stale because it has been open for 90 days with no activity. It will automatically close after 30 more days of inactivity. Reopen the issue with /reopen. Mark the issue as fresh by adding the comment /remove-lifecycle stale.

[evankanderson]

/remove-lifecycle stale