CNCF Tech Doc Recommendations: Umbrella Issue #6301
Description
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:
cncf/techdocs#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.
✏️ Rename pages
Audit page and heading titles for consistency and accuracy.
✏️ Update technical overview
Write a conceptual overview of Knative where the "Concepts"
section is in the current documentation, but be much more comprehensive.
✏️ Update Installation to better orient users
Add "roadmap" information to orient readers in the Installation section of the
documentation.
✏️ Reorganization issues
This issue suggests several changes to the documentation's organization to
improve usability and consistency.
✏️ 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.
✏️ 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.
✏️ Add a glossary
Add a glossary of terms to the technical documentation.
✏️ 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?
✏️ Edit for conformance to style guide
Edit the website for conformance to the [Knative style guide].
✏️ Improve troubleshooting
Improve Knative troubleshooting instructions by adding explanations.
✏️ Fill out the Eventing API
Improve the explanations in the Eventing API.
✏️ 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.
✏️ Make install downloads findable
Move and relabel the download file section so that the files are easy to find.
✏️ 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.