Docs review and update

[jhkrug]

Keeping track of @jhkrug's docs work.

The goals?

• Docs as part of community building. How to progress?
• Rancher Prime integration. What's possible?
• Enterprise-ready lighthouse support goal. What's possible beyond good documentation.
• Clear document architecture with process for deciding an information chunks place in the architecture. Clear for personas what to look at.
• Finished first full review, readability, grammar, spelling, style-guide. 'General improvements' to improve useability
• Documentation coverage. Are core topics completely covered? Are topics missing?
• Site styling. Anything? Not that important?

Architecture

Do we need any structure changes to better match Diataxis/Divio guidelines? Yes, we do.

Acceptance criteria

• Feat: Reorg docs following Diataxis doc system #152
• Decide on a new docs/Sidebar layout #332
• Information architecture experimentation. #348
• Implement new docs layout and sidebar #351
• Rework Custom CAs docs #354 - Comes out of the work on Implement new docs layout and sidebar #351. Needs further attention.

once #332 is complete then it makes sense to finish:

• Setup canonical links #325

Full review

Questions to be addressed for each of the issues (issues roughly correspond to a review and update of a page or section) below:

• Is the content up to date and accurate.
• Any screenshots reflect the current state of products.
• Installation scripts and tutorial examples work as listed and produce the documented output.
• Grammar and style reflects the guidelines (Microsoft & SUSE).

General

• Installation guide #206
• Common tasks page updates #211
• explanations/mutating policies review and update #212
• Distributing docs text refresh #217
• Refresh 'testing policies' #219
• Refresh explanations/Context aware policies #220
• Refresh how-tos/PSP migration #221
• Refresh how-tos/Using Pod security admission #222
• Refresh how-tos/Secure supply chain #223
• Refresh how-tos/Custom certificate authorities #224
• Typo fix. Also corrected some alignment issues with examples. #226
• Another look at Audit Scanner #234
• Revisit introduction.md. KDAC -> Policy Engine. #251
• Revisit architecture.md diagrams #258
• Redo header and footer to be similar arrangement to that of Epinio. #270

Reference docs

• refresh/reference/architecture #248
• Refresh reference/OCI Registries support #253
• Refresh reference/Threat model #254
• Refresh reference/Monitor mode #255
• Refresh reference/Rancher Fleet #256

Policy specification

• Language review for policy specification 1, 2 and 3. #359 will close - 01-intro-spec.md
• Language review for policy specification 1, 2 and 3. #359 will close - 02-settings.md
• Language review for policy specification 1, 2 and 3. #359 will close - 03-validating-policies.md
• Review and update policy specification 4 & 5 #360 will close - 04-mutating-policies.md
• Review and update policy specification 4 & 5 #360 will close - 05-context-aware-policies.md
• Review and update policy specification reference on host capabilities #361 will close - host-capabilities 1 - intro
• Review and update policy specification reference on host capabilities #361 will close - host-capabilities 2 - sig verify
• Review and update policy specification reference on host capabilities #361 will close - host-capabilities 3 - container registry
• Review and update policy specification reference on host capabilities #361 will close - host-capabilities 4 - net
• Review and update policy specification reference on host capabilities #361 will close - host-capabilities 5 - crypto
• Review and update policy specification reference on host capabilities #361 will close - host-capabilities 6 - kubernetes

Operator Manual

• Refresh language and add link to explanation of OpenTelemetry baggage. #363 will close this. Metrics reference
• CRD docs integration #263 CRDs
• Already done as part of earlier work. Verification Config

Rancher UI Extension

• Minor refresh of the UI extension howtos #364 closes - Quickstart
• Minor refresh of the UI extension howtos #364 closes - Monitoring
• Minor refresh of the UI extension howtos #364 closes - Tracing

Air gap

• Refresh of air gap installation howto #369 completes - Requirements
• Refresh of air gap installation howto #369 completes - Installation

Writing Policies

• Introduction to writing policies #282

Rust

#295 closes all these:

• Refresh writing policies in Rust #294
• 04-write-validation-logic.md
• 05-mutation-policy.md
• 06-logging.md
• 07-build-and-distribute.md

Go

• Refresh writing policies in Go #321

Rego

• PR Refresh language for tutorial on Rego. #368 - 01-intro-rego.md
• PR Refresh language for tutorial on Rego. #368 - 02-builtin-support.md

Rego - gatekeeper

• PR Refresh language for tutorial on Rego. #368 - 01-intro.md
• PR Refresh language for tutorial on Rego. #368 - 02-create-policy.md
• PR Refresh language for tutorial on Rego. #368 - 03-build-and-run.md
• PR Refresh language for tutorial on Rego. #368 - 04-distribute.md

Rego open-policy-agent

• PR Refresh language for tutorial on Rego. #368 - 01-intro.md
• PR Refresh language for tutorial on Rego. #368 - 02-create-policy.md
• PR Refresh language for tutorial on Rego. #368 - 03-build-and-run.md
• PR Refresh language for tutorial on Rego. #368 - 04-distribute.md

WASI

Closed by #314

• 01-intro-wasi.md
• 02-raw-policies.md

Others

All covered in, and will be closed by #308.

• dotnet.md
• dsl.md - Deleted
• javascript.md - Deleted
• metadata.md
• other-languages.md
• swift.md
• typescript.md

Testing policies

• will be closed by Refresh tutorial on policy testing. #366 - 01-intro.md
• will be closed by Refresh tutorial on policy testing. #366 - 02-policy-authors.md
• will be closed by Refresh tutorial on policy testing. #366 - 03-cluster-operators.md

Site Styling

[jhkrug]

I think this first pass can be marked done.