Skip to content

docs: reorganise the docs around what a user is doing and rewrite pages that bury their point - #1435

Merged
chio-labs-delivery[bot] merged 13 commits into
mainfrom
docs/reorganize-docs
Nov 13, 2026
Merged

chio-labs-delivery[bot] merged 13 commits into
mainfrom
docs/reorganize-docs

Conversation

@kvlonge

@kvlonge kvlonge commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Why

The docs put reference material in a new user's path: a 5,900-word configuration page, a naming spec and five overlapping rename pages come before models and tests. Several pages open with edge cases before the main point. This reorganises the site around what a user is doing and rewrites the pages that bury their message.

Changes

  • New sidebar: Getting Started, Build models, Testing, Correctness, Ship, Refactor, Investigate, Advanced, Adapters, Integrations, Reference, CLI (grouped by task, sqb <command> titles).
  • New page: Set up a project. Splits: Unit tests / Testing reference, SQL macros / SQL macro reference, Recall / Sharing Recall in ClickHouse, Adapters / Custom adapters.
  • Rewrites: Contracts (what a contract is first, check_declared_columns as one sentence, a runtime table per materialization, upstream contracts), Reusable column schemas, Naming rules, Column and model migrations, sqb rename, Observability, Quickstart (adds a "Change a model" step).
  • Configuration reference: warehouse groups move to Snowflake, limit tables to sqb build, migration-origin policy to Model migrations.
  • Removes duplicated sections, history wording, implementation detail and stale facts; adds a redirect for the old enums-and-constants page.
  • STYLE.md: Refactoring replaces Column migrations as an exemplar; adds rules on openings and one rule per paragraph.
  • Regenerated the docs skill references.

Verification

  • npm run build and scripts/check_links.py dist: 129 pages, 0 broken links.
  • npm test (Playwright) passes.
  • scripts.generate_docs_skill and scripts.check_docs_skill are up to date.
  • Quickstart output re-run against the published playground.
  • Behaviour claims in rewritten pages checked against the compiler and executor source.

@chio-labs-delivery
chio-labs-delivery Bot added this pull request to the merge queue Nov 13, 2026
Merged via the queue into main with commit d159d0a Nov 13, 2026
32 of 33 checks passed
@chio-labs-delivery
chio-labs-delivery Bot deleted the docs/reorganize-docs branch November 13, 2026 00:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant