Documentation improvements as per CNCF recommendations

[jhkrug]

As per CNCF recommendations report.

This issue lays out the needed/suggested tasks:

Specific

• Documentation layout description page and personas page. #485

• Who is the documentation for, what do they get?

  • Provide a page with a description of personas using and developing Kubewarden, at whom the documentation is aimed. Also, Documentation layout description page and personas page. #485.
    • For each persona provide: their likely experience, Kubernetes knowledge, goals in using the docs, expected learnings.
  • Investigate and do one (maybe both, thought required) of:
    • Provide a map/list of pages relevant to each persona. Continues/extends work began in Provide guided paths to documentation for differing personas. #400 and Learning paths #425.
    • Each page should have a statement regarding the personas the page is aimed at?

• Kubewarden what is/introduction page review

  • New user section. If you are new to KW ... blah, blah. CNCF recommendation - New to Kubewarden. #526
  • Core features and benefits. What problem(s) does KW solve? The value proposition? Sub-issue KW value proposition - CNCF #529
  • Link to and review/improve the explanation/architecture (referred to as the 'Overview' in the CNCF critique) page
  • Provide a recent developments and future roadmap section. Possibly point to an additional page.

• Quick start page review

  • Link to the improved architecture document to provide context CNCF recommendation - New to Kubewarden. #526
  • Where can KW be installed? On prem? Cloud? Well, it's really wherever your K8s clusters are.
  • Helm charts and their role in installation. More context and links to further information
  • Better description of prerequisites and their configuration
  • Common issues and errors
  • Validate copy/paste installation of basic installation on basic K8S. How deep to go?
  • Review main components section
  • Format and legal value for attributes table. Mention, but probably in a new linked page.
  • Further worked examples for differing scenarios?

• New main docs section 'Policy management (& development)'?

  • Management
  • Development tutorials (Rust, etc.)

General

• Review for active voice.
  • Introductory pages. See CNCF recommendations - Introductory pages review for active voice, language and some formatting. #539
  • Explanation pages. See Explanation section - updated language and active voice. CNCF suggestion. #541
  • Reference
    • Ref pages, part 1. See CNCF suggested review for language/active. Reference, part1 #542
    • Ref - Upgrade path. See Updates to the upgrade path documentation. #609.
    • Ref - Monitor mode, see CNCF active language review for monitor mode. #550
    • Ref - OCI Registry Support, see CNCF active language review for OCI registries. #551
    • Ref - Threat Model, see CNCF active language review for threat model. #552
    • Ref - Policy evaluation timeout, see policy evaluation timeout language review for active voice as part of the CNCF recommendations. #638
    • Ref - Verification configuration format, see Verification configuration language review  #639.
    • Ref - sources.yaml, see sources.yaml language refinement for CNCF. #640.
    • Ref - specification section. See Specification reference language improvements for CNCF. #641.
    • Ref - specification/host-capabilities. See Reference/spec/host capabilities language review as per CNCF guidance. #647.
    • Ref - security hardening/webohhoks. See webhook hardening language improvements as per CNCF suggestions. #648
  • Howtos
    • Airgap. See Airgap howto. CNCF suggested language improvements. #651
    • More improvements to Howtos (part 1). See Howtos (part 1) language improvements as per CNCF recommendations. #668.
    • Further improvements to Howtos (part 2). (security hardening). See howtos (part 2) language improvement as per CNCF recommendations #669.
    • more on howtos. See webhook and telemetry language improvements and some formatting. #670.
    • UI extension howtos UI extension, language improvements. #671.
    • Cert expiry, audit scanner argocd howtos. Some language improvements in Howtos. #687
    • More airgap, common tasks. Some language improvements. #707
• Style guide consistency, currently Microsoft(y), but SUSE docs have their own style guide. Which is a little different.