Skip to main content

Contributing to the documentation

Resources​

note

The conventions on this page are also written up for AI coding agents in .github/instructions/documentation/ (content structure, authoring style, JSON schemas, versioning, release notes, gateway/OpenAPI, site components). Keep the two in sync when you change a convention.

How to write documentation​

Try to keep following key-items into mind:

  • Follow a similar structure (navigation path) as the application itself where it makes sense.
  • Don't document something that's changed too often. Outdated documentation is worse than no documentation at all.
  • If possible, embed documentation in the application itself:
    • Use @Schema(description = "...") where possible, and expose them to the FE.
  • Don't create "empty" documentation
    • Avoid pages that are empty or contain no real information
    • Avoid Todo placeholders

How to define a different title in the side bar​

At the top of the markdown file, add the following frontmatter (replace the title as needed):

---
title: "Name in sidebar"
---

How to generate JSON schema's in the API​

  • Run ./generate-json-schemas.sh in kubernetes/local

Textual resources for consistency​

Let's use/copy below examples throughout the documentation for consistency. If a better icon is found, please do a search and replace for all the old instances.

  • Labels
    • Various colors: GREY RED GREEN PURPLE BLUE YELLOW
    • Modules: RBA
  • Icons:
    • Mandatory: ✅ (yes) or ❌ (no)
    • Titles:
      • 🎯 Functional documentation
      • ⚙️ Configuration or settings
      • 🛠️ Technical documentation
      • 🔗 References
      • ⤴️ Migration guide
    • Various:
      • ℹ️ Information
      • ⚠️ Warning
      • ️✏️ Edit
      • ❔ Question
    • If more are needed, the Emojipedia is a good resource.

Some other Layout components​

warning

This shows a panel with a color and icon

note

This shows a panel with a color and icon

important

This shows a panel with a color and icon

tip

This shows a panel with a color and icon

caution

This shows a panel with a color and icon

Expandable info

Some information text here

And some more text here

Some code block
{
  "list": [
    {
      "object": {
        "field": "jdfuenvcma"
      },
      "field": "jdfuenvcma"
    }
  ]
}

Mermaid: see Syntax​

Examples: