Overview

This guide covers the standards and conventions for writing technical documentation in the Arda Platform documentation site. The site is built with Astro Starlight and all content is written in Markdown (.md) or MDX (.mdx).

PR conventions

This repository uses PR-body changelogs and a queued CI/CD pipeline. Three rules to remember as an author:

Do not edit CHANGELOG.md. Put your changelog entry in the PR description under a ## CHANGELOG heading (the repo’s PR template has the placeholder). The post-merge changelog-assembly workflow writes CHANGELOG.md and tags the release for you.
Use the PR template — it has ## Summary, ## CHANGELOG, ## Closes, ## Verification sections. The changelog-check workflow will fail your PR if the ## CHANGELOG block is missing or empty.
Reviewer policy is path-scoped via CODEOWNERS. PRs that only touch src/content/docs/roadmap/ need no approval; everything else needs an approving review from @Arda-cards/engineering. Use the REVIEW-REQUIRED label to force a review even on roadmap-only PRs.

Step-by-step author guidance, including labels (auto-merge, REVIEW-REQUIRED, manual-changelog), preview/production deploy URLs, and the post-merge automation, lives in Getting Started. The shared design across documentation and arda-frontend-app is documented at Queued CI/CD.

Frontmatter and build rules

Every page carries a YAML frontmatter block. title, description (40–300 characters), and author are required and enforced at build time — make pr-checks fails the schema validation on a violation. Internal links must include the .md extension; the same make pr-checks run catches broken or extensionless links through the Lychee link checker.

Beyond those enforced rules there are a few conventions that reviewers expect — no duplicate in-body # H1, code fences carry a language tag, and every PlantUML diagram is paired with a 1–3 sentence prose summary — but those are not currently enforced by the build.

See Frontmatter and Build Rules for the canonical reference, including required and recommended fields, enumerated values, style for description, MDX-specific constraints, what each make pr-checks step actually catches, and how to read the build failures when something is off.

Document Organization

Content is organized by audience and purpose across the following top-level sections:

Section	Audience	Content Type
`product/`	End users (shop managers, operators)	How-to guides, concept explanations, platform guides
`domain/`	Domain experts, analysts	Information model, domain concepts, glossary
`current-system/`	Developers and engineers	Architecture, API reference, patterns, data model, runtime
`vision/`	All stakeholders	Future-state architecture, target designs
`roadmap/`	Project managers, stakeholders	Project status, backlog, ideas
`process/`	Engineers, team leads	Development workflows, SRE procedures, craft guides
`technology/`	Engineers	Technology-specific references (Cedar, AG Grid, etc.)
`legal/`	Compliance, management	Licensing, certification, compliance
`decisions/`	Engineers, architects	Decision records, discussion logs
`about/`	Authors, contributors	Authoring guides, templates, style conventions

Within each section, follow the Diataxis framework:

Tutorial — A learning-oriented walkthrough. Leads the reader through a complete task to build competence.
How-To Guide — A goal-oriented set of steps. Assumes the reader knows what they want; explains how to do it.
Reference — Information-oriented material. Accurate, complete, and terse. Suitable for lookup.
Explanation — Understanding-oriented discussion. Explores context, background, and rationale.

Each article should serve one Diataxis type. If content spans two types, split it into separate articles.

File and Path Conventions

File names use lowercase kebab-case: adding-items.md, purchase-order-v1.md.
Directories use lowercase kebab-case as well.
Every directory that contains content pages must have an index.md serving as the section landing page.
Cross-repository path references use /repo-name/path/to/file (no system absolute path).

Links

Use standard Markdown file-path links with the .md extension for all internal references. A build-time remark plugin (remark-resolve-md-links) automatically rewrites these to Starlight-compatible URLs, so source files stay clean and navigable in editors and GitHub.

Recommended forms:

Link syntax	Meaning
`[text](sibling.md)`	Page in the same directory
`[text](./sibling.md)`	Same (explicit relative)
`[text](../other-section/page.md)`	Page in a parent or sibling directory
`[text](sub-dir/index.md)`	Section landing page in a subdirectory
`[text](sibling.md#section-anchor)`	Specific heading on another page
`[text](#anchor)`	Heading on the current page

Rules:

Always include the .md extension on internal links — the plugin only processes .md links.
Use relative paths, not absolute paths starting with /.
Do not manually convert links to Starlight’s directory URL form (e.g., ../sibling/). The plugin handles this automatically.
External links use full URLs: [text](https://example.com).
Anchor-only links (#section) are passed through unchanged.
Links inside fenced code blocks are not modified.
Link text: Use the target document’s title frontmatter value or # Heading as the link text. For example, link to the PlantUML Guide as [PlantUML Guide](plantuml-guide.md), not [click here](plantuml-guide.md).

Link Resolution — How the Plugin Transforms Paths

Starlight serves each .md page as a directory URL (e.g., page.md becomes /section/page/). The remark-resolve-md-links plugin compensates for this by adding one ../ to every .md link in non-index pages at build time. Authors do not need to account for this adjustment — write standard filesystem-relative paths with the .md extension and the plugin handles the rest.

Key rules:

Write the path exactly as the filesystem relative path from your file to the target file.
Always include .md — a link like ../sibling (without .md) bypasses the plugin and breaks under the /documentation/ base path.
Index pages (index.md) do not get the extra ../ — their URL is already their directory.

Worked example:

Given this file structure:

docs/
  product/
    features/
      upload.md          ← source file (non-index)
    personas/
      sam.md             ← target file

From upload.md to sam.md, the filesystem relative path is ../personas/sam.md. Write exactly that — the plugin will transform it to ../../personas/sam/ at build time, which resolves correctly from the page URL /product/features/upload/.

Validation: Run make test-preview locally before pushing. This builds with the preview base path (/documentation/) which is stricter than the default production build and will catch resolution errors that pass locally.

To compute the correct link and verify it resolves correctly, use the helper script:

# From the documentation/ directory:
node tests/resolve-link.mjs <source-file> <target-file>
# Example:
node tests/resolve-link.mjs \
  src/content/docs/product/features/upload.md \
  src/content/docs/product/personas/sam.md
# Output: ../personas/sam.md

The script simulates the plugin transformation and verifies the resulting URL resolves to the target page. If the link would break, it prints a warning with the expected vs. actual resolution.

Adding and Removing Sections

For a step-by-step guide on creating and removing documentation sections — including using the built-in Section Creator widget available on the local dev server — see Adding and Removing Sections.

Provenance

Content provenance is tracked centrally in the Content Provenance page rather than inline within individual files. When adding new content migrated from another source, add an entry to the provenance table for the appropriate section.

Markdown Formatting

General Rules

One blank line before and after headings, lists, blockquotes, and code blocks.
Use - for bulleted lists (not *).
Use spaces only for indentation — no tabs.
Use 2 spaces per indentation level in lists and code blocks.
Use --- (three hyphens) for horizontal rules.

Headings

The document title is the only H1 (#). Do not repeat the title frontmatter value in the body.
Use ## through #### for sections and subsections.
Do not skip heading levels (e.g., do not jump from ## to ####).

Admonitions

The documentation site uses Starlight’s admonition syntax.

In .md files, use the triple-colon shorthand:

:::note
Useful information that users should know, even when skimming content.
:::

:::tip
Helpful advice for doing things better or more easily.
:::

:::caution
Urgent info that needs immediate user attention to avoid problems.
:::

:::danger
Advises about risks or negative outcomes of certain actions.
:::

In .mdx files, use the <Aside> component:

import { Aside } from '@astrojs/starlight/components';

<Aside type="tip">
Helpful advice for doing things better or more easily.
</Aside>

Available types: note (default), tip, caution, danger.

Starlight Components (MDX only)

When writing .mdx files, the following Starlight components are available:

import { Tabs, TabItem, Card, CardGrid, LinkCard, Steps, Code, Aside } from '@astrojs/starlight/components';

<Tabs> / <TabItem> — Tabbed content panels
<Card> / <CardGrid> — Content cards for navigation or feature highlights
<LinkCard> — Card that links to another page
<Steps> — Numbered step-by-step instructions
<Code> — Enhanced code blocks with title, line highlighting, and diff markers
<Aside> — Callout boxes (note, tip, caution, danger)

See the Starlight documentation for full usage details.

Tables

Tables work in standard Markdown .md files. See Markdown Gallery for syntax examples.

Code Blocks

Use fenced code blocks with a language identifier:

```kotlin
data class Item(val id: UUID, val name: String)
```

Supported identifiers include kotlin, typescript, sql, yaml, json, http, bash, plantuml, text.

Diagrams

PlantUML

Use PlantUML for architecture, sequence, and domain model diagrams. See PlantUML Guide for syntax, conventions, the C4 shape gallery, and common pitfalls.

A build-time remark plugin (remark-plantuml) converts plantuml code blocks into inline SVG images during the site build. No external image service is needed — just write the PlantUML source directly in your Markdown.

Embed a PlantUML diagram using a fenced code block:

```plantuml
@startuml
hide footbox
title My Sequence Diagram

actor User
participant System
User -> System ++ : Action
return Response
@enduml
```

Draw.io

For layout-heavy diagrams (network topology, UI wireframes, complex flowcharts), use Draw.io:

Create a file named <name>.drawio.svg in the _assets/ or assets/ subdirectory next to the document.
Edit with the Draw.io desktop app, the web app at app.diagrams.net, or the IntelliJ/VS Code plugin. The editing data is embedded in the SVG file itself.
Embed in the document: ![Alt text](_assets/diagram.drawio.svg).

Templates

Reusable templates for common document types are in the Templates section. Use the template that matches the document’s purpose:

General templates:

Template	When to Use
Architecture Decision Record	Documenting technology and design decisions
Behavior Description	Use cases and scenarios within the functional domain taxonomy
Bug Report	Defect documentation with reproduction steps
Code Review Report	Quality or architectural review findings
Decision Log	Open questions, design alternatives, and their resolutions during planning sessions
Design Document	Technical architecture for new components or significant features
Implementation Analysis	Spec-vs-implementation gap analysis
Implementation Plan	Describing a planned technical change for engineers to implement
Operational Runbook	Step-by-step operational procedures
Pull Request Description	PR body for any repository
Refactoring Plan	Planned incremental refactoring with risk assessment
Security Audit Report	Recording security review findings and remediation
Task Plan	Team Lead coordination plan for multi-agent work
Test Plan	Acceptance test scope and coverage matrix
Threat Model	STRIDE-based threat analysis of features and components
User Persona	Creating user persona profiles
User Story	Defining feature requirements in user story format

Backend service templates (in Backend Service Templates):

Template	When to Use
Feature Requirements	Specifying a new feature with domain modeling and structured requirements
Incremental Service Requirements	Specifying changes to an existing Kotlin backend service
New Service Implementation	Specifying a new Kotlin backend service module from scratch
Task Specification	Defining a scoped implementation task with acceptance criteria

Style Conventions

Write in the second person (“you”, “your”) for guides addressed to a reader.
Use present tense: “The service validates the request” (not “will validate”).
Prefer active voice: “The engineer implements the endpoint” (not “the endpoint is implemented by the engineer”).
Spell out abbreviations on first use: “Operation Authorization Module (OAM)”.
Use backticks for inline code, file names, directory paths, and configuration keys: `index.md`, `maturity`.
Reference specific files, line numbers, and code paths where applicable — concrete references are more useful than vague descriptions.
Use bold for UI labels and terms being defined: Item, AVAILABLE, maturity.
Capitalize the names of Arda-specific concepts and domain terms: Universe Pattern, State Engine, Action Pattern.