maplibre 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.