Skip to content

PRDCT-376: split the Transformations section into Diátaxis pages#987

Open
Iamfle4ka wants to merge 15 commits into
feat/PRDCT-372-snowflake-splitfrom
feat/PRDCT-376-transformations-section
Open

PRDCT-376: split the Transformations section into Diátaxis pages#987
Iamfle4ka wants to merge 15 commits into
feat/PRDCT-372-snowflake-splitfrom
feat/PRDCT-376-transformations-section

Conversation

@Iamfle4ka

@Iamfle4ka Iamfle4ka commented Jun 24, 2026

Copy link
Copy Markdown
Collaborator

Splits the entire Transformations section into single-purpose Diátaxis pages (how-to / reference / explanation) with thin link-hubs at the old URLs, using the validated PRDCT-372 Snowflake pilot pattern, template, and checklist.

Built on the PRDCT-372 pilot foundation (first 5 commits) — can be reviewed as one PR or split into stacked PRs (PRDCT-372 → main, then this → PRDCT-372). Contains no phase3-demo WIP.

What's included

Pilot foundation (PRDCT-372): schema keywords+type, the Snowflake split, and revamp/ template + checklist.

Group 1 — code-backed:

  • bigquery → hub + how-to + reference
  • oracle → revised how-to + documented the optional schema field
  • duckdb → hub + how-to + reference + explanation

Group 2 — README-only SoT:

  • python-plain → hub + how-to + reference (tutorial facet folded into how-to)
  • r-plain → hub + how-to + reference; R 4.0.5 → 4.4.1
  • variables → hub + how-to + explanation
  • transformations/index → fixed the broken "Other features" table row; frontmatter (kept unified to preserve #writing-scripts anchors)

Group 3 — dbt subtree (Confluence debt): stripped all {: width} leftovers, added frontmatter to all 6 pages; judged 41 empty-alt images per page — kept 12 genuine UI-locator shots with (flagged) alt, dropped 29 decorative/CLI-output shots and made the text stand alone.

Group 0 — light touch: frontmatter + type only on array-splitter, binary, plots, mappings, code-patterns, snowflake-migration.

Standards applied

  • One Diátaxis type per page; titles/descriptions in user vocabulary; title/description/keywords/type frontmatter; old URLs preserved (hubs + existing redirect_from).
  • Reference verified against code SoT where it exists; the component schemas/READMEs aren't in this repo, so unverifiable facts are flagged inline TODO(human-review) — nothing invented, renamed, or removed.
  • All code/config in fenced blocks; no code in screenshots.

Human-review queue

Consolidated in revamp/PRDCT-376-human-review.md (63 inline markers): reference facts to verify vs component code, UI labels, dbt alt-text (images weren't viewable during editing), the index table-row fix, and Diátaxis mapping notes.

Verification

npm run build clean (268 pages); link/anchor/redirect checks pass; node scripts/audit-phase2.mjs shows no new issues on the touched pages.

🤖 Generated with Claude Code

Nikita and others added 12 commits June 24, 2026 19:36
@claude
PRDCT-376: split BigQuery transformation into how-to + reference
4352253 
Block 0: how-to + reference. Thin hub at the unchanged URL. Query limits and the
Query timeout parameter (default 0) carried over; the 2-hour GCP figure and
config fields flagged TODO(human-review) — schema not in this repo.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: revise Oracle transformation how-to + document optional `s…
0ae2ccb 
…chema` field

Block 0: already how-to (no split). Reshaped to the standard how-to (steps,
confirm, troubleshooting) and added the optional `schema` config field from
oracle-transformation ConfigDefinition.php; exact default/behavior flagged
TODO(human-review).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: split DuckDB transformation into how-to + reference + expl…
fc44613 
…anation

Block 0: how-to + reference + explanation. Thin hub at the unchanged URL.
Settings, backend memory figures, and parameter names (threads/max_memory_mb)
flagged TODO(human-review) — configuration.py not in this repo.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: wire Group 1 (bigquery, duckdb) splits into the sidebar
92a67c8 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: split Python transformation into how-to + reference
c3a0db6 
Block 0: how-to + reference + tutorial. Mapped to how-to + reference + hub —
the tutorial/dev-walkthrough facet folded into the how-to ("Develop and debug"),
since type is constrained to how-to|reference|explanation. Kept the plaintext-
secrets warning prominent. README is the SoT (not in repo) → limits/versions/
preinstalled packages flagged TODO(human-review).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: split R transformation into how-to + reference; bump R 4.0…
b7ce986 
….5 -> 4.4.1

Block 0: how-to + reference + tutorial (tutorial folded into how-to). Updated the
documented R version to 4.4.1 as instructed. README SoT (not in repo) → limits/
versions flagged TODO(human-review). Example sub-pages (array-splitter, plots,
binary) left untouched (Group 0).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: split Variables & Shared Code into how-to + explanation
9047d5d 
Block 0: explanation + how-to. Thin hub at the unchanged URL. Fixed a stale
mappings anchor (#snowflake-loading-type -> #loading-type-snowflake-and-bigquery).
No code SoT — no fields documented.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: fix broken "Other features" table row + add frontmatter on…
80325af 
… Transformations index

Block 0: explanation + reference. Kept as a single combined landing (not URL-split)
to preserve load-bearing anchors like #writing-scripts referenced across the
section. Corrected the malformed "Other features" row (removed a garbled row,
rowspan 9 -> 8) and flagged it for human review.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: wire Group 2 (python, r, variables) splits into the sidebar
c088188 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: clean up dbt subtree — alt text, drop decorative images, f…
b63f757 
…rontmatter

Group 3 (Confluence debt): stripped all Jekyll `{: width}` leftovers and added
frontmatter (title/description/keywords/type) to all 6 dbt pages.

Images (41 total, empty alt): judged per page.
- cli (13): all CLI/terminal output, not UI locators → dropped; text stands alone.
  The generated source-file screenshot → TODO(human-review: add example).
- transformation (16): kept 10 genuine config-screen locators with flagged alt;
  dropped 6 decorative job-log/redundant shots.
- cloud (9): kept 2 config-screen locators; dropped 7 output/storage shots.
- flows (3): decorative → dropped; expanded text to stand alone.
- index, troubleshooting: frontmatter only.

Kept-image alt text is context-derived (images not viewable here), prefixed
`TODO(human-review: alt unverified)` so it is flagged but never empty.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: Group 0 light touch — frontmatter + type on already-clean …
f57cec9 
…pages

No split. Added description/keywords/type to: r-plain/array-splitter, binary,
plots (how-to examples); mappings (reference); code-patterns (how-to);
duckdb/snowflake-migration (how-to).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: consolidated human-review queue for the Transformations split
509ffa1 
Folds every inline TODO(human-review) from Groups 1-3 into one list (reference
facts to verify vs code SoT, UI labels, dbt alt text, the index table-row fix,
and Diátaxis mapping notes).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@linear

linear Bot commented Jun 24, 2026

Copy link
Copy Markdown

PRDCT-376

@vercel

vercel Bot commented Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
connection-docs Ready Ready Preview, Comment Jun 24, 2026 11:36pm

Request Review

@Iamfle4ka Iamfle4ka changed the base branch from main to feat/PRDCT-372-snowflake-split June 24, 2026 20:48
@claude
PRDCT-376: transcribe dbt CLI config output to fenced blocks (masked)
6ccee04 
Corrected the over-applied "drop all" on dbt/cli: the `kbc dbt init` example
screenshot was config/command output, so per our own rule it is transcribed to
fenced blocks, not dropped — env vars (shell), generated profiles.yml, and a
generated models/_sources/*.yml. All values are placeholders; secrets
(KBC_STORAGE_API_TOKEN, password) masked, no real IDs (secret-scanned).

Also flag dbt/cloud dbt_cloud_trigger status-table columns for human review.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: section-wide screenshot transcription audit
0868af6 
Verified every screenshot in the Transformations section against the
"code/config never as an image → transcribe" rule:
- dbt CLI config output: already transcribed (env vars, profiles.yml, sources yml).
- dbt transformation/cloud kept images are UI config screens (not code); the
  dbt run command and profiles.yml are already fenced blocks.
- mappings, duckdb/snowflake-migration, r-plain examples, index: UI / result /
  chart screenshots — nothing transcribable.
- code-patterns "Generated Code" screenshot is the one remaining code-in-an-image;
  flagged TODO(human-review) (content is pattern-specific, not viewable here).

Updated the consolidated human-review list accordingly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@claude
PRDCT-376: reconcile types + verified facts with PRDCT-354 audit (Blo…
32830a4 
…ck 0/A/B)

Now that the Block 0 classification is accessible, aligned #987 with it:

- Schema: add `tutorial` to the type enum.
- Types per Block 0: cli, r-plain array-splitter/binary/plots, duckdb/
  snowflake-migration -> tutorial; troubleshooting -> how-to; flows -> explanation.
- Resolved TODO flags verified by Block B (vs component code): snowflake
  query_timeout=7200 + ABORT_TRANSFORMATION + copy/clone; bigquery Query timeout
  default 0 + ABORT_TRANSFORMATION; duckdb threads/max_memory_mb/dtypes_infer/
  syntax_check/duckdb_version + supported versions {1.5.2,1.4.4} + sync actions;
  oracle optional db.schema. Kept only platform-level unverifiable flags.
- Fixed broken anchors (Block A): #phases/#dependencies (index) and
  #new-transformations (code-patterns, mappings) — overlaps Devin PR #981.
- Updated revamp/PRDCT-376-human-review.md (Resolved section + reconciliation note).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Iamfle4ka