How we write docs

This is the Krumware documentation standard (PAAP-203), adapted for Astro Starlight. It applies to this starter and to every docs site built from it.

Choose the right section (Diátaxis)

Decide what the reader needs, then pick a section:

Teaching a newcomer, with guaranteed outcomes → tutorial.
Helping someone complete a known task → how-to guide.
Describing the machinery (commands, APIs, config) → reference.
Explaining a concept or the “why” → explanation.

Frontmatter

Every content page sets the fields in the frontmatter reference: title, description, doc-type, doc-topic, and doc-persona where a persona applies.

Style

Don’t repeat the title as an H1 in the body.
Open with one or two sentences stating what the page covers and who it’s for.
Use sentence-case headings with a logical hierarchy.
Declare a language on every code block (bash, yaml, and so on).
Link internally with root-relative paths (for example /reference/ci/); avoid absolute self-links.
End each page with a ## See also section linking related pages.

Page templates

Copy one of these into src/content/docs/<section>/ and fill it in.

Tutorial

---
title: Do X, step by step
description: What the reader will have built by the end.
doc-type: tutorial
doc-persona: [developer]
doc-topic: <topic>
---

One or two sentences on what this teaches and the end state.

## Prerequisites

## Steps

## See also

How-to guide

---
title: Accomplish a specific task
description: The task, in one line.
doc-type: how-to
doc-persona: [developer]
doc-topic: <topic>
---

One or two sentences on the task and its assumptions.

1. First step

## See also

Reference

---
title: Thing being described
description: One line.
doc-type: reference
doc-topic: <topic>
---

Factual description — tables, fields, values.

## See also

Explanation

---
title: Concept
description: One line.
doc-type: explanation
doc-topic: <topic>
---

Background and reasoning. No step-by-step instructions.

## See also

Build gate

The site build fails on broken internal links, so check your links before opening a PR. A green build is required to merge — see CI and previews.