Writing docs

Who reads these docs

• Geologists and hydrogeologists, often reading English as a second language. They need to know what each field means in the field.
• Developers building tools, databases and editors on the format. They need code that works against the current packages.
• AI agents working for either group, reading the same pages as Markdown.

Write for all three: plain sentences, one idea each, no marketing language, no jargon a field geologist would not use unless it is explained.

The rules

1. Link to the spec, don't restate it. The specification in spec/ is the only place a rule is stated. A page that depends on a rule explains it in plain words and links to the spec heading, for example [level sign convention](/format/spec/v2/format-reference#level-sign-convention). If a guide needs a rule the spec lacks, the spec gets the rule first.
2. Full examples use well fences. Every complete .well document is a ```well fence or a ::well-preview{example="<id>"} block, so CI validates it. Fragments and deliberately invalid snippets use json fences.
3. Two entry points. Geologist-facing pages (getting started, concepts) explain field meaning without code. Developer pages show code, checked against the current package APIs.
4. Frontmatter. Every page has a title and a description. The description is used in search results, llms.txt and SEO, so make it a full sentence that says what the page covers.
5. No duplicate title. The page header shows title. Omit a leading # Heading in the body, or make it identical to title.
6. Sentence case for titles and headings: "Getting started", not "Getting Started".
7. Code that runs. Run new snippets against the packages before publishing. State the output only when you have seen it.

The content components page lists the blocks you can use: callouts (::note, ::tip, ::warning, ::caution), ::code-group, ::tabs, ::steps, ::do-dont, mermaid diagrams and ::well-preview.

Links and anchors

• Link site pages by path: /format/concepts/units-and-precision.
• Spec pages are at /format/spec/v2/<file>, /format/spec/reference/fgdc-textures and /format/spec/v1/well-format. Heading anchors are the ones GitHub generates, so ## `bore_hole[].drilling_method` becomes #bore_holedrilling_method--recommended-values-since-v23. Copy them from the rendered page or GitHub; do not guess.
• Object pages: /format/reference/objects/<object> (for example bore-hole). API pages: /<package>/api/<kind>/<Name>. Changelogs: /<package>/changelog.
• The JSON Schema is linked at https://welldot.org/schema/v2/well.schema.json, never copied.
• Repository files are linked on GitHub: https://github.com/welldothq/welldot/blob/main/<path>.

check:links fails the build on a broken link or anchor, including links into the spec.

Adding a page

Pages live in apps/docs/content/en/ and their path is their route. Numeric prefixes set the sidebar order and are dropped from the route: format/2.concepts/3.vocabularies.md is /format/concepts/vocabularies.

content/en/
  index.md                     the landing (layout: landing)
  format/                      the .well format section
    index.md                   section home
    1.getting-started/ 2.concepts/ 3.guides/ 4.reference/ 5.spec/ 6.changelog.md
  core/ utils/ render/         one section per package
    index.md  1.getting-started/  2.guides/   (api/ is generated)
  ai/  contributing/

1. Create the file in the right folder, with a numeric prefix for its position.
2. Add title and description frontmatter. navigation.title sets a shorter sidebar label.
3. Write the page following the rules above.
4. Run the checks below.

A directory without an index.md appears in the sidebar as a group named after the folder.

Generated pages

Never edit these by hand; they are rebuilt on every dev, build and generate and are not committed:

• content/en/<package>/api/**: the API reference, generated from the TSDoc in the package sources by TypeDoc. To change it, edit the TSDoc.
• content/en/format/reference/objects/**: the object reference, generated from the JSON Schema. To change it, change the Zod schemas in @welldot/core (and the spec).

The spec pages under /format/spec and the package changelogs are read straight from spec/ and packages/*/CHANGELOG.md.

Run the site locally

The docs need Node 22.5 or later (they use Node's built-in SQLite).

pnpm install
pnpm turbo build --filter=docs^...   # build the packages the docs read
pnpm --filter docs dev               # http://localhost:3001

Before opening a pull request:

pnpm --filter docs check:examples    # every .well snippet validates
pnpm --filter docs generate          # the site builds
pnpm --filter docs check:links       # every link and anchor resolves

Translations

This release is English only. Pages are organized so a Portuguese edition can be added under content/pt/ later; an English edit never waits for a translation, and a translation that falls behind is flagged automatically.