Writing conventions for Toborlife docs¶

Use these conventions in every product repo’s docs/ tree so this hub stays consistent and easy to scan.

Nav is generated from folders and filenames. Structure and naming matter as much as prose.

Short vs long pages¶

Split by job, not by how much you know.

Kind	Purpose	Length guide	Filename / placement
Short (overview)	Orient the reader: what it is, when to use it, where to go next	~½–1 screen; rarely more than ~150–200 lines	`index.md` in a section folder, or a small topic page
Long (detailed)	Teach or specify: full how-to, schema, API, lifecycle	As long as needed, but one concern per page	Named topic file, e.g. `SCHEMA_REFERENCE.md`, `authentication.md`

How they work together¶

Section index.md = short front door
Explain the area in a few paragraphs, list the main tasks, and link to the detailed pages. Do not paste the full reference here.
Detailed pages = depth
One detailed page per concern (e.g. schema reference vs episode lifecycle). Cross-link back to the section overview and to sibling detailed pages.
If a page grows past ~300–400 lines or mixes two jobs
Split it:
overview stays short on index.md or a “guide” page
tables / exhaustive lists move to a *_REFERENCE.md (or reference.md)
step-by-step flows move to a dedicated how-to page
Don’t duplicate
Short page: summary + links. Long page: full detail. Repeat only a one-line reminder on the long page (“This is the schema reference for …”), not the whole overview.

Examples¶

Good

docs/database/
  index.md                      # short: what the DB docs cover + links
  DATABASE.md                   # design / rationale (medium–long)
  SCHEMA_REFERENCE.md           # long reference tables
  EPISODE_CLIP_LIFECYCLE.md     # long how-to / flow

Avoid

docs/database/
  index.md                      # 2,000 lines of schema + lifecycle + intro

When to keep something short on purpose¶

Placeholder sections (backend/frontend stubs): a short index.md with scope + “docs coming” is better than empty or fake depth.
Cross-cutting pointers: a short page that only routes to other sections is fine.

When long is required¶

Schema / field dictionaries
End-to-end lifecycles
Multi-step operational runbooks
API or config surface area that people will search and skim with the TOC

Long pages should still use clear ## / ### headings so the right-hand TOC works.

Voice and audience¶

Write for someone new to that area, not only the author.
How-tos: second person (“Run…”, “Set…”).
Reference: third person / declarative (“The API returns…”, “Column X stores…”).
Be direct. Skip filler (“simply”, “just”, “basically”).

Page templates¶

Short overview (`index.md` or intro page)¶

# Area name

One or two sentences: what this area is and who it’s for.

## What’s in this section

- [Detailed topic A](topic-a.md) — one-line what you’ll find
- [Detailed topic B](topic-b.md) — …

## Start here

If you only do one thing: …

Long how-to¶

# Task or flow name

One or two sentences: outcome of this guide.

## Prerequisites

- …

## Steps

1. …
2. …

## Verify

How to confirm it worked.

## See also

- [Section overview](index.md)
- [Related reference](schema-reference.md)

Long reference¶

# Name reference

One sentence: what this documents (and what it does *not*).

## Overview

Optional short context (a few sentences max).

## Tables / fields / APIs

| Name | Type | Meaning |
|------|------|---------|

## See also

- [Section overview](index.md)
- [Related how-to](lifecycle.md)

Headings¶

One # (H1) per page; then ## / ### in order (don’t skip levels).
Prefer outcome-oriented headings (“Create a batch”, not “Details”).
Keep heading text short; put nuance in the paragraph below.

Code and commands¶

Fence with a language tag (bash, json, sql, yaml).
Use copy-pasteable examples; mark placeholders (YOUR_API_KEY, <episode_id>).
State env / permissions before the first command that needs them.
Prefer real shapes over pseudocode for APIs and config.

Admonitions (MkDocs Material)¶

Use sparingly:

!!! note
    Short context.

!!! warning
    Something that can break prod or data.

!!! tip
    Optional shortcut.

Don’t stack several admonitions in a row.

Links¶

Within the same repo docs/, use relative links (../database/SCHEMA_REFERENCE.md).
To another product’s docs, link pages on this hub (or name the section tab). Don’t assume sibling folders on disk.
Don’t rely on README/wiki content outside docs/ — it isn’t published here.

Naming (files and prose)¶

Folders/files: kebab-case (extraction-worker, episode-clip-lifecycle.md).
Match UI and code names exactly in prose.
Expand acronyms once on first use (“Row Level Security (RLS)”).
Prefer stable product terms over internal nicknames.

Quality bar before merge¶

[ ] Right length for the job (short overview vs long detail; split if mixed).
[ ] H1 + short intro present.
[ ] Headings form a useful TOC on long pages.
[ ] Links resolve under docs/.
[ ] No “TODO: fill this in” on pages you intend to publish.
[ ] Section index.md links to every detailed page in that folder.

Repo wiring (for maintainers)¶

Each source repo should also:

Keep published docs under docs/.
Include a notify workflow so hub rebuilds when docs/ changes.
Be listed in the hub’s sources.yml.