# Docs Writing

> Write or edit repository documentation, KDoc, contributor guidance, and PR descriptions. Covers this project's audience, documentation structure, and compiled examples.

- Skill: `maplibre/docs-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add maplibre/docs-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/maplibre/docs-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: maplibre (https://skillmd.com/u/maplibre)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/maplibre/docs-writing

---


# Writing

Write plain technical English for readers who may use English as a second
language. Library users usually know Compose but need MapLibre concepts
explained. Contributors know Kotlin Multiplatform and need the reasons for
project-specific decisions.

Lead with the fact, action, or decision the reader needs. Prefer concrete nouns,
direct verbs, and explicit conditions. Avoid promotional language, stock
transitions, and metaphors that obscure API behavior. Include the detail the
reader needs to understand the subject.

Use paragraphs for explanations, lists for steps or parallel items, and tables
for comparisons. Headings use sentence case and identify sections that readers
can navigate. Link to existing explanations instead of repeating them.

## Documentation site

Pages under `docs/src/content/docs/` follow the site's Diátaxis structure:

- Getting started helps a new user integrate a working map.
- Guides complete a specific task and explain choices where they arise.
- Concepts explain behavior and design.
- API reference comes from KDoc and defines the public API contract.

Choose the page's primary purpose and keep it focused. Introduce the common path
on the site and link to API details. Include platform differences, conditions,
and implementation details when they affect the reader's decision or ability to
complete the task.

Pages import Kotlin examples from `// #region` blocks in
`demo-app/common/src/*/kotlin/org/maplibre/compose/docsnippets/`, which compile
with the demo app. Add or update a snippet region instead of embedding an
untested Kotlin example in a page. Title file-oriented code blocks with the
destination filename, such as `build.gradle.kts` or `App.kt`.

## KDoc and pull requests

KDoc defines behavior, parameter semantics, lifecycle requirements, and platform
limitations that callers need.

PR descriptions follow `.github/PULL_REQUEST_TEMPLATE.md` and `AI_POLICY.md`.
Explain what reviewers need to understand the change, with detail proportional
to its complexity. Report validation accurately.