knative
CNCF Tech Doc Recommendations: Umbrella Issue
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.
- [x] https://github.com/knative/docs/issues/6302
✏️ Rename pages
Audit page and heading titles for consistency and accuracy.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] https://github.com/knative/docs/issues/6308
✏️ Add a glossary
Add a glossary of terms to the technical documentation.
- [x] 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].
- [x] https://github.com/knative/docs/issues/6311
✏️ Improve troubleshooting
Improve Knative troubleshooting instructions by adding explanations.
- [x] https://github.com/knative/docs/issues/6312
✏️ Fill out the Eventing API
Improve the explanations in the Eventing API.
- [x] 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.
- [x] 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.
- [x] https://github.com/knative/docs/issues/6316
Hi @dwelsch-esi the PR #6485 marks the last checklist in this list, the implementation is final, The PR is ready to be merged!
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!
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.