[SergiyKolesnikov]

Description

Update the documentation: fix wording and typos, ensure clarity and consistency

Checklist

• I have run make style and fixed any issues
• I have added tests for my changes (if applicable)
• All existing tests pass (make fast-test)
• My commits are signed off (git commit -s) per the DCO

Summary by CodeRabbit

• Documentation
  • Clarified how audits differ from tests, when audits run, and what happens when one fails.
  • Updated guidance on managed models, including how engines update their tables and how SQLMesh handles their schemas.
  • Clarified when tests run with sqlmesh test and sqlmesh plan, including options for selecting or skipping tests.
  • Updated DAG generation instructions to use sqlmesh dag FILE and open the generated HTML file in a browser; removed the Graphviz installation instructions.

[coderabbitai]

Walkthrough

Documentation updates clarify audits and tests, describe managed-model behavior, and revise the instructions for generating a DAG.

Changes: Audits and tests

Layer / File(s)	Summary
Audit and test guidance docs/concepts/audits.md, docs/concepts/tests.md	The documentation distinguishes data-quality audits from transformation tests. It describes when audits run and how sqlmesh plan selects tests by default and with selection options.

Managed models

Layer / File(s)	Summary
Managed-model description docs/concepts/models/managed_models.md	The introduction describes engine-maintained tables, SQLMesh schema management, and the guidance to use a SQL model instead of a Python model.

DAG guide

Layer / File(s)	Summary
DAG generation instructions docs/guides/models.md	The guide describes DAG nodes and dependency arrows, and explains how to run sqlmesh dag FILE and open the generated HTML file.

Priority: Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Suggested reviewers: treysp, cmgoffena13

Merge Risk: Minimal · up to 98c9e

No concrete merge-blocking issue is established by the documentation changes.

Architecture risk: Low · up to 98c9e

The change affects 1 system.

Changed systems: docs

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — docs (service) was modified; 4 changed files map to changed impact.

Before / after behavior

• observed — Modified behavior in docs/concepts/audits.md: The introduction now defines audits as checks of actual model output against quality criteria, contrasts them with tests of transformation logic, and clarifies that audits run when a plan is applied. It retains the default halt-on-failure behavior and reference to non-blocking audits, while revising the description of audit users and the issues they catch.
• observed — Modified behavior in docs/concepts/models/managed_models.md: The introduction now explains automatic updates when source tables change, notes that engines use different background processes and creation parameters, and describes MANAGED models as engine-maintained while SQLMesh maintains their schema. It retains the external-model guidance but removes the explanation that the main benefit is reading from tables SQLMesh does not track.
• observed — Modified behavior in docs/concepts/models/managed_models.md: The Python-model warning is reformatted and its instruction changes from “use a SQL model instead” to “Use a SQL model instead.”
• observed — Modified behavior in docs/concepts/tests.md: The overview now explains that tests compare model outputs with expected outputs for specified inputs, describes their role in checking transformation logic, and distinguishes them from audits that check data quality. It replaces the previous overview’s statements about regression protection and when tests run, including its plan-testing options.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title "doc: fix wording and typos, ensure clarity and consistency" matches the changeset. The PR edits documentation files (audits, managed models, tests, and the DAG guide) to fix wording and typ…
Description check		The description states the purpose of the change: updating the documentation to fix wording and typos and to ensure clarity and consistency. It keeps the repository template's Checklist section. It om…
Docstring Coverage		No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title "doc: fix wording and typos, ensure clarity and consistency" matches the changeset. The PR edits documentation files (audits, managed models, tests, and the DAG guide) to fix wording and typos and improve clarity and consistency. The title names the type of change and its general purpose. It does not name the specific documents, so it is broad, but it is related to the main change.

Full details: Description check

Explanation

The description states the purpose of the change: updating the documentation to fix wording and typos and to ensure clarity and consistency. It keeps the repository template's Checklist section. It omits the template's Test Plan section, and it does not name the edited documents. The checklist shows only the DCO sign-off as checked. The other items, including running make style and make fast-test, are unchecked, and the description does not explain why.

Resolution

Optional improvements: add a Test Plan section that says how the documentation changes were checked, for example by reviewing the rendered Markdown files. Name the edited documents (audits, managed models, tests, and the DAG guide). Confirm whether make style and make fast-test were run, or explain why they were not needed for a documentation-only change.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (4 skipped: 4 unsupported.)

Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🔇 Additional comments: 1

docs/guides/models.md-241-241: 1

241-241: Minor · Maintainability & Code Quality · Quick win

⚠️ Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Use the configured Markdown code-block style.

markdownlint reports MD046 for this fenced block. Convert it to the repository's required indented style, or update the Markdown configuration if fenced blocks are intentional.

Source: Linters/SAST tools

---

Review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 6ce77984-6738-49a8-a252-64c73eb257a1

Commits

Reviewing files that changed from the base of the PR and between f6527ff and 98c9ebf.

Files selected for processing: 4

• docs/concepts/audits.md
• docs/concepts/models/managed_models.md
• docs/concepts/tests.md
• docs/guides/models.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.