Skip to main content

Contributing to Documentation

This guide explains how to add or edit documentation.

File Structure​

Every markdown document gets its own folder to store assets:

32-billing/
├── _category_.yml              # Defines order
├── overview/
│   ├── index.md                # Main content
│   ├── billing.drawio          # Source file (editable)
│   └── billing.drawio.svg      # Rendered for embedding
├── models/
│   ├── index.md
│   └── models.drawio.svg
└── credit-system/
    └── index.md

Naming Conventions​

Areas (10-19)​

  • Use Johnny Decimal ranges
  • Format: XX-XX-area-name/
  • Example: 10-19-infrastructure/

Categories (21, 22)​

  • Use two-digit numbers within the area range
  • Format: XX-category-name/
  • Example: 21-api-walkthrough/

Pages (No Numbers)​

  • Use descriptive names without numbers
  • Format: topic-name/index.md
  • Example: authentication/index.md

Page Ordering​

Page order is controlled via _category_.yml files, NOT by numbering folders:

label: "API Walkthrough"
position: 1
items:
  - setup
  - api-design
  - authentication    # To insert, just add a line here
  - controllers

To insert a new page:

  1. Create the folder with index.md
  2. Add the folder name to the items array in _category_.yml

Adding Diagrams​

We use DrawIO for diagrams. Store both the source and rendered files:

  1. Create diagram in DrawIO (VS Code extension recommended)
  2. Save as .drawio in the page folder
  3. Export as .drawio.svg for embedding
  4. Reference in markdown:
![Billing Overview](./billing-overview.drawio.svg)

Frontmatter​

Optional frontmatter for pages:

---
sidebar_label: 'Custom Label'
description: 'Brief description for SEO'
tags: [billing, credits]
---

Best Practices​

  1. One topic per page: Keep pages focused
  2. Use relative links: ../other-page or ./diagram.svg
  3. Include diagrams: Visual explanations help understanding
  4. Start with "Why": Explain the purpose before the "how"
  5. Keep examples real: Use actual code from the codebase