Document Known Issues

Content Structure

Follow the problem-cause-action (PCA) structure.

### Heading that summarizes the issue

Paragraphs, code blocks, and images that describe the following:

- Problem that users will or might encounter
- Indicators of the problem (for example, unwanted system behavior and error messages)
- Root cause of the problem
- Actions that users can take to remediate or mitigate the problem
- When the problem is expected to be fixed

Related issue: [#Number](Link)

Examples:

• Documentation: https://docs.harvesterhci.io/v1.5/upgrade/v1-4-0-to-v1-4-1#3-upgrade-is-stuck-in-the-waiting-reboot-state
• KB article: https://harvesterhci.io/kb/iso_boot_fails_with_sbat_errror

Content Placement

Question: Where do we want users to look for such information?

• Feature-specific pages

  Examples:

  • Upgrade: https://docs.harvesterhci.io/v1.5/upgrade/v1-4-1-to-v1-4-2#2-high-cpu-usage
  • Third-Party Storage Support: https://docs.harvesterhci.io/v1.5/advanced/csidriver#1-infinite-image-download-loop

  Advantages:

  • The context is clear. A user who intends to perform an upgrade is likely to go directly to the relevant doc page.
  • Manual linking can be minimized. Docusaurus automatically creates a ToC for each page, so users will likely see "Known Issues" even if they do not scroll all the way down.

• Troubleshooting section

  Examples:

  • Harvester: https://docs.harvesterhci.io/v1.5/troubleshooting/harvester#manually-collect-data-for-support-bundle
  • Virtual Machines: https://docs.harvesterhci.io/v1.5/troubleshooting/vm#virtual-machine-ip-address-not-displayed

  Advantages:

  • The information may be easier to locate. Content chunks of the same type are organized in one location and clearly labeled.
  • Feature-specific pages do not become too long and cluttered. Users can focus on understanding concepts and following procedures.

Other Uses of PCA

• Describing limitations

  Example: Air-Gapped Environment: https://docs.harvesterhci.io/v1.5/airgap#harvester-ui-extension-with-rancher-integration

• Mentioning issues in admonitions (note/important/caution/warning)

  Example: Harvester CSI Driver: https://docs.harvesterhci.io/v1.6/rancher/csi-driver