Contributing to Documentation¶

Guidelines for adding, editing, or reviewing documentation on this site.

Before You Start¶

Documentation lives in the docs/ directory of the musingly-docs repository. Each service repository may also contain a docs/ directory that is included here via Git submodules.

To build and preview locally:

make install   # install Python dependencies once
make dev       # starts live-reload server at http://127.0.0.1:8000

File Naming¶

Directory Structure¶

docs/
├── <section>/
│   ├── index.md          ← Section landing page (required)
│   └── <topic>.md        ← Topic pages

Create a new directory only when a section has or will have more than one page. A single-page section is just a .md file, not a directory.

Page Structure¶

Every page must follow this structure:

# Page Title                    ← exactly one H1, first line

One sentence describing what this page covers.

## Section heading              ← H2 for top-level sections

### Subsection heading          ← H3 for subsections within a section

Rules:

• Every page has exactly one H1, which is the first line.
• Headings never skip levels. H2 follows H1, H3 follows H2.
• H4 and below are reserved for reference tables only.
• Section headings use Title Case: ## Getting Started, not ## Getting started.

Headings and Icons¶

Do not add emoji to headings or navigation labels. They reduce scannability and do not render consistently across screen readers and search results.

## Overview        ← correct
## 🏗️ Overview    ← incorrect

Code Blocks¶

Always specify a language identifier. Never use a plain fence.

```python          ← correct
def hello():
    pass
```

```              ← incorrect (no language)
def hello():
    pass
```

Common identifiers: python, typescript, javascript, bash, yaml, json, sql, mermaid.

Admonitions¶

Use admonitions sparingly — one per page is a reasonable limit. Four types are available:

!!! note
    For supplementary information that is useful but not critical.

!!! tip
    For a recommendation or shortcut.

!!! warning
    For something that could cause data loss, downtime, or unexpected behavior.

!!! danger
    For irreversible or destructive actions.

Do not use admonitions as decorative section breaks or to wrap regular content.

Tables¶

Use tables for comparative or reference data. Not for prose.

| Column A | Column B | Column C |
|---|---|---|
| Value | Value | Value |

Prefer two-column key/value tables over wide multi-column tables when documenting configuration options.

Links¶

Use descriptive link text. Never use "click here", "here", or bare URLs as link text.

See the [deployment guide](../services/deployment.md).    ← correct
See [here](../services/deployment.md) for deployment.     ← incorrect

Use relative paths for internal links. Use absolute URLs for external links.

What Not to Include¶

Documentation pages must be authored content. Do not include:

• AI assistant responses or conversation transcripts
• Citation artifacts such as [1], [2], [3] reference notation
• "This section will be populated later" placeholder text
• I'll help you... or other AI preamble language
• Raw XML tags such as <analysis> or <response>

If a page is not ready, use the in-progress template below rather than leaving a stub.

In-Progress Pages¶

When a section is planned but not yet written, use this template:

# Section Title

!!! note "In progress"
    This page is planned. See the outline below for what it will cover.

## Planned content

- Topic one — brief description
- Topic two — brief description
- Topic three — brief description

To contribute this section, see the [contributing guide](../getting-started/contributing.md).

Submitting Changes¶

1. Create a branch from main.
2. Make your changes in docs/.
3. Preview locally with make dev.
4. Open a pull request. The CI build will validate the site.
5. Request review from a maintainer.

The GitHub Actions workflow builds the site on every pull request. A failing build blocks merge.