CNCF Tech Doc Recommendations: Umbrella Issue

[dwelsch-esi]

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.

• Separate technical documentation from the project page #6302

✏️ Rename pages

Audit page and heading titles for consistency and accuracy.

• Rename pages #6303

✏️ Update technical overview

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

• Update technical overview #6304

✏️ Update Installation to better orient users

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

• Update Installation to better orient users #6305

✏️ Reorganization issues

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

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

• Document the kn CLI on the site #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.

• Revise the Security and threat disclosure page #6308

✏️ Add a glossary

Add a glossary of terms to the technical documentation.

• Add a glossary #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?

• Review graphics #6310

✏️ Edit for conformance to style guide

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

• Edit for conformance to style guide #6311

✏️ Improve troubleshooting

Improve Knative troubleshooting instructions by adding explanations.

• Improve troubleshooting #6312

✏️ Fill out the Eventing API

Improve the explanations in the Eventing API.

• Fill out the Eventing API #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.

• Write a Getting Started page #6314

✏️ Make install downloads findable

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

• Make install downloads findable #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.

• Truncate search results #6316

[evankanderson]

/kind documentation

[lakxy]

/assign

[lakxy]

Hi @dwelsch-esi
the PR #6485 marks the last checklist in this list, the implementation is final,
The PR is ready to be merged!

[lakxy]

Hey @evankanderson
What doo you think about issue #6315 . I think it is general practice.
However if it were to be resolved would you prefer updates in documentation/ a separate downloads page,
let me know & I will get it done!

[lakxy]

/unassign

[evankanderson]

Hey @evankanderson What doo you think about issue #6315 . I think it is general practice. However if it were to be resolved would you prefer updates in documentation/ a separate downloads page, let me know & I will get it done!

I added a comment in #6315. Since this is an umbrella issue, I'd probably leave it un-assigned unless you want to take on the work of making sure that each item is closed.

[github-actions]

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.