Skip to content

Documentation guide

Documentation lives under docs/ and is built with MkDocs.

Frontmatter requirements

All documentation pages that are part of the MkDocs site (listed in mkdocs.yml under nav:) must include YAML frontmatter with a description field. The description is used to populate DOCS_MAP.md and helps readers understand the page's purpose.

Markdown snippets under docs/includes/ are auto-included via pymdownx.snippets and should not have frontmatter (for example, docs/includes/abbreviations.md).

---
description: Concise description of page content and purpose. Can be up to 4 sentences providing context for what the reader will learn.
---

# Page Title

Content starts here...

The sync_docs_map.py script extracts descriptions from frontmatter to populate DOCS_MAP.md. Pages without descriptions show [Description needed].

python3 skills/project-docs/scripts/sync_docs_map.py --check
python3 skills/project-docs/scripts/sync_docs_map.py

Principles

  • Write for the audience (Getting started vs How-to vs Concepts vs Reference).
  • Keep examples copy-pastable and aligned with actual code. If code changes, update docs in the same PR.
  • Prefer links to reference docs instead of duplicating normative details.

Local preview

Install Python deps:

python -m pip install -r requirements.txt

Run locally:

./gradlew docsServe

Or run MkDocs directly (without regenerating Dokka output):

mkdocs serve

Contribution workflow

  1. Create or edit docs under docs/ following the Diataxis structure:
  2. getting-started/: Tutorials and quick start guides
  3. how-to/: Task-oriented guides for specific goals
  4. concepts/: Explanatory content for understanding
  5. reference/: API and SPI documentation for lookup

  6. modules/: Per-module technical documentation

  7. Preview locally with ./gradlew docsServe or mkdocs serve

  8. Update navigation in mkdocs.yml if adding new pages

  9. Cross-reference related docs instead of duplicating content

  10. Verify code examples compile and run correctly

Style guidelines

  • Use active voice: "Configure the client" not "The client can be configured"
  • Include runnable code examples for every feature when possible
  • Use admonitions for callouts: 
    !!! note
    Important information here.

!!! warning
    Potential issues to be aware of.

!!! tip
    Helpful hints for users.
  • Link to Dokka API docs for class references using relative paths
  • Follow existing voice in neighboring documents for consistency
  • Keep headings hierarchical: # for title, ## for sections, ### for subsections

File naming

Use lowercase with hyphens:

getting-started.md   # correct
GettingStarted.md    # incorrect
getting_started.md   # incorrect

Adding new pages

  1. Create the markdown file in the appropriate directory
  2. Add the page to mkdocs.yml under nav:
  3. Add cross-references from related pages
  4. Verify navigation with mkdocs serve