frist draft finish

ijac13 · ijac13 · commit 6dbb5d4081fb · 2025-09-10T17:43:57.000+08:00
diff --git a/claude/restructure-report.md b/claude/restructure-report.md
@@ -0,0 +1,188 @@
+# Documentation Restructure Report
+
+## Overview
+This report analyzes the documentation restructuring changes in the [PR#34](https://github.com/DataRecce/recce-docs/pull/34), comparing production URLs with the new structure and categorizing content changes.
+
+## 1. URL Structure Comparison (Production → New)
+
+### Navigation Structure Changes
+
+**Production Structure:**
+- Overview
+- Getting Started  
+- Web UI
+- Command Line Interface
+- Advanced Features
+- Scenarios
+- Architecture
+- Privacy & Terms
+- Cloud (Beta)
+
+**New Structure:**
+- What's Recce (1-whats-recce)
+- Getting Started (2-getting-started)
+- Visualized Change (3-visualized-change)
+- Downstream Impacts (4-downstream-impacts)
+- Data Diffing (5-data-diffing)
+- Collaborate Validation (6-collaboration)
+- CI/CD (7-cicd)
+- Technical Concepts (8-technical-concepts)
+
+### Complete URL Mapping
+
+| Status | Production URL | New URL | Notes |
+|--------|---------------|---------|-------|
+| **SAME** | `/` (external redirect) | `/` (external redirect) | Home link unchanged |
+| **SAME** | `/blog/` (external) | `/blog/` (external) | Blog link unchanged |
+| **MODIFIED** | `/` (Overview) | `/1-whats-recce/` | Main landing page restructured |
+| **ARCHIVED** | `/demo/` | `/archived/demo/` | Demo page archived |
+| **MODIFIED** | `/get-started/` | `/2-getting-started/oss-vs-cloud/` | Split into multiple pages |
+| **ARCHIVED** | `/configure-diff/` | `/archived/configure-diff/` | Configuration guide archived |
+| **MODIFIED** | `/get-started-jaffle-shop/` | `/2-getting-started/get-started-jaffle-shop/` | Moved to section 2 |
+| **ARCHIVED** | `/start-with-dbt-cloud/` | `/archived/start-with-dbt-cloud/` | DBT Cloud guide archived |
+| **MODIFIED** | `/installation/` | `/2-getting-started/installation/` | Moved to section 2 |
+| **MODIFIED** | `/features/lineage/` | `/3-visualized-change/lineage/` | Reorganized under visualized change |
+| **MODIFIED** | `/features/query/` | `/5-data-diffing/query/` | Moved to data diffing section |
+| **MODIFIED** | `/features/checklist/` | `/6-collaboration/checklist/` | Moved to collaboration section |
+| **MODIFIED** | `/features/recce-debug/` | `/7-cicd/recce-debug/` | Moved to CI/CD section |
+| **ARCHIVED** | `/features/recce-run/` | `/archived/recce-cloud/recce-run/` | Archived under cloud |
+| **MODIFIED** | `/features/recce-summary/` | `/7-cicd/recce-summary/` | Moved to CI/CD section |
+| **MODIFIED** | `/features/state-file/` | `/8-technical-concepts/state-file/` | Moved to technical concepts |
+| **MODIFIED** | `/features/preset-checks/` | `/7-cicd/preset-checks/` | Moved to CI/CD section |
+| **ARCHIVED** | `/features/node-selection/` | `/archived/` | Integrated into other pages |
+| **MODIFIED** | `/features/impact-radius/` | `/4-downstream-impacts/impact-radius/` | New section created |
+| **MODIFIED** | `/features/breaking-change-analysis/` | `/4-downstream-impacts/breaking-change-analysis/` | Moved to downstream impacts |
+| **ARCHIVED** | `/features/column-level-lineage/` | `/3-visualized-change/column-level-lineage/` | Moved to visualized change |
+| **MODIFIED** | `/reference/configuration/` | `/8-technical-concepts/configuration/` | Moved to technical concepts |
+| **MODIFIED** | `/guides/scenario-dev/` | `/7-cicd/scenario-dev/` | Moved to CI/CD section |
+| **MODIFIED** | `/guides/scenario-pr-review/` | `/7-cicd/scenario-pr-review/` | Moved to CI/CD section |
+| **MODIFIED** | `/guides/scenario-ci/` | `/7-cicd/scenario-ci/` | Moved to CI/CD section |
+| **MODIFIED** | `/guides/best-practices-prep-env/` | `/7-cicd/best-practices-prep-env/` | Moved to CI/CD section |
+| **ARCHIVED** | `/architecture/overview/` | `/archived/overview/` | Architecture overview archived |
+| **ARCHIVED** | `/agreement/privacy-policy/` | External link | Now links to reccehq.com |
+| **ARCHIVED** | `/agreement/cookies-policy/` | External link | Now links to reccehq.com |
+| **ARCHIVED** | `/agreement/terms-of-use/` | External link | Now links to reccehq.com |
+| **ARCHIVED** | `/recce-cloud/*` | `/archived/recce-cloud/*` | Most cloud docs archived |
+
+### New Pages Created
+
+| New URL | Description |
+|---------|-------------|
+| `/1-whats-recce/community-support/` | New community support page |
+| `/2-getting-started/oss-vs-cloud/` | New comparison page |
+| `/2-getting-started/start-free-with-cloud/` | New cloud onboarding |
+| `/2-getting-started/cloud-5min-tutorial/` | New quick tutorial |
+| `/3-visualized-change/code-change/` | New code change visualization |
+| `/3-visualized-change/multi-models/` | New multi-model documentation |
+| `/4-downstream-impacts/metadata-first/` | New metadata approach guide |
+| `/4-downstream-impacts/transformation-types/` | New transformation types guide |
+| `/5-data-diffing/row-count-diff/` | New row count diffing guide |
+| `/5-data-diffing/profile-diff/` | New profile diffing guide |
+| `/5-data-diffing/value-diff/` | New value diffing guide |
+| `/5-data-diffing/topK-diff/` | New top-K diffing guide |
+| `/5-data-diffing/histogram-diff/` | New histogram diffing guide |
+| `/6-collaboration/share/` | New sharing documentation |
+| `/7-cicd/setup-cd/` | New CD setup guide |
+
+## 2. Content Change Analysis
+
+### New Content Requiring Full Review
+
+| Page | Status | Review Required |
+|------|--------|----------------|
+| `1-whats-recce/index.md` | **NEW CONTENT** | ✅ Full review needed (completely rewritten introduction) |
+| `1-whats-recce/community-support.md` | **NEW PAGE** | ✅ Full review needed |
+| `2-getting-started/oss-vs-cloud.md` | **NEW PAGE** | ✅ Full review needed (detailed comparison table) |
+| `2-getting-started/start-free-with-cloud.md` | **NEW PAGE** | ✅ Full review needed |
+| `2-getting-started/cloud-5min-tutorial.md` | **NEW PAGE** | ✅ Full review needed |
+| `3-visualized-change/code-change.md` | **NEW PAGE** | ✅ Full review needed |
+| `3-visualized-change/multi-models.md` | **NEW PAGE** | ✅ Full review needed |
+| `4-downstream-impacts/impact-radius.md` | **NEW PAGE** | ✅ Full review needed |
+| `4-downstream-impacts/metadata-first.md` | **NEW PAGE** | ✅ Full review needed |
+| `4-downstream-impacts/transformation-types.md` | **NEW PAGE** | ✅ Full review needed |
+| `5-data-diffing/row-count-diff.md` | **NEW PAGE** | ✅ Full review needed (detailed tutorial with GIFs) |
+| `5-data-diffing/profile-diff.md` | **NEW PAGE** | ✅ Full review needed |
+| `5-data-diffing/value-diff.md` | **NEW PAGE** | ✅ Full review needed |
+| `5-data-diffing/topK-diff.md` | **NEW PAGE** | ✅ Full review needed |
+| `5-data-diffing/histogram-diff.md` | **NEW PAGE** | ✅ Full review needed |
+| `6-collaboration/share.md` | **NEW PAGE** | ✅ Full review needed |
+| `7-cicd/setup-cd.md` | **NEW PAGE** | ✅ Full review needed |
+
+### Partial New Content / Enhanced Pages
+
+| Page | Change Type | Review Required |
+|------|-------------|----------------|
+| `2-getting-started/installation.md` | **ENHANCED** | 🔄 Partial review (expanded from basic pip install) |
+| `3-visualized-change/lineage.md` | **ENHANCED** | 🔄 Partial review (significantly enhanced with new sections, tips, and explanations) |
+| `3-visualized-change/column-level-lineage.md` | **MOVED + MINOR EDITS** | 🔄 Minor review (moved from features/, minimal content changes) |
+| `6-collaboration/checklist.md` | **ENHANCED** | 🔄 Partial review (expanded with detailed workflow steps) |
+
+### Minor Changes / Terminology Updates
+
+| Page | Change Type | Review Required |
+|------|-------------|----------------|
+| `5-data-diffing/query.md` | **MINOR EDITS** | ⚪ Minimal review (mostly same content, minor formatting) |
+| `4-downstream-impacts/breaking-change-analysis.md` | **MINOR EDITS** | ⚪ Minimal review (removed icon, minor text changes) |
+
+### Restructured Only (Same Content, Different URL)
+
+| Page | Change Type | Review Required |
+|------|-------------|----------------|
+| `2-getting-started/get-started-jaffle-shop.md` | **MOVED** | ⚪ No content review (just moved) |
+| `7-cicd/best-practices-prep-env.md` | **MOVED** | ⚪ No content review (moved from guides/) |
+| `7-cicd/preset-checks.md` | **MOVED** | ⚪ No content review (moved from features/) |
+| `7-cicd/recce-debug.md` | **MOVED** | ⚪ No content review (moved from features/) |
+| `7-cicd/recce-summary.md` | **MOVED** | ⚪ No content review (moved from features/) |
+| `7-cicd/scenario-ci.md` | **MOVED** | ⚪ No content review (moved from guides/) |
+| `7-cicd/scenario-dev.md` | **MOVED** | ⚪ No content review (moved from guides/) |
+| `7-cicd/scenario-pr-review.md` | **MOVED** | ⚪ No content review (moved from guides/) |
+| `8-technical-concepts/configuration.md` | **MOVED** | ⚪ No content review (moved from reference/) |
+| `8-technical-concepts/state-file.md` | **MOVED** | ⚪ No content review (moved from features/) |
+
+### Archived Content
+
+| Page | Status | Action |
+|------|--------|--------|
+| All `/archived/*` files | **ARCHIVED** | ⚪ No review needed (preserved for reference) |
+
+## 3. Summary Statistics
+
+- **Total Pages Analyzed**: 47 active pages + 11 archived pages
+- **New Pages**: 16 pages requiring full content review
+- **Enhanced Pages**: 4 pages requiring partial review  
+- **Minor Changes**: 2 pages requiring minimal review
+- **Restructured Only**: 10 pages (no content changes)
+- **Archived Pages**: 11 pages moved to archived/
+- **External Links**: 3 pages converted to external links
+
+## 4. Review Priority Matrix
+
+### High Priority (New Content)
+- Section 1: What's Recce (2 pages)
+- Section 2: Getting Started (3 new pages) 
+- Section 3: Visualized Change (2 new pages)
+- Section 4: Downstream Impacts (3 new pages)
+- Section 5: Data Diffing (5 new pages)
+- Section 6: Collaboration (2 pages)
+- Section 7: CI/CD (1 new page)
+
+### Medium Priority (Enhanced Content)
+- Enhanced installation guide
+- Enhanced lineage documentation
+- Moved but enhanced column-level lineage
+
+### Low Priority (Restructured Only)
+- All moved pages with no content changes
+- Archived pages (for reference only)
+
+## 5. Recommendations
+
+1. **Content Review Focus**: Prioritize the 18 completely new pages for thorough review
+2. **Navigation Testing**: Test all URL redirects to ensure no broken links
+3. **Image Assets**: Verify all image paths have been updated correctly (significant reorganization in assets/)
+4. **SEO Impact**: Consider 301 redirects for changed URLs to maintain search rankings
+5. **User Experience**: The numbered learning path (1-8) provides better progressive learning structure
+
+---
+
+*Report generated from PR changes analysis comparing feature/pla-488-update-doc-structure-with-existing-content branch with main branch.*
diff --git a/claude/terminology.md b/claude/terminology.md
@@ -20,6 +20,15 @@ This guide helps maintain consistent, data-team-friendly language across all Rec
 | **code change** | code modification | Specific term for data team workflows |
 | **validation workflow** | testing workflow, QA process | How teams use Recce |
 | **diff** | comparison, delta | Data teams familiar with git diff, use freely |
+| **state file** | session file, cache | Stores validation results and checks for later use |
+| **preset checks** | default tests, template checks | Pre-configured validation rules for projects |
+| **lineage diff** | dependency comparison | Visual comparison of model relationships |
+| **breaking change analysis** | impact assessment | Automated detection of schema changes |
+| **value diff** | data comparison | Row-by-row data validation between environments |
+| **profile diff** | summary statistics | Column-level statistical comparisons |
+| **histogram diff** | distribution analysis | Numeric data distribution comparisons |
+| **top-K diff** | frequency analysis | Categorical data frequency comparisons |
+| **row count diff** | record count validation | Quick data volume verification |
 | **Recce**| recce | this is the brand name, should always use "Recce" | 
 | **dbt** | DBT | this is the brand name, should always use lower cases| 
 
@@ -37,6 +46,13 @@ This guide helps maintain consistent, data-team-friendly language across all Rec
 | **automated validation** | CI/CD pipeline | Data processing vs deployment automation |
 | **change review** | code review | Reviewing data changes vs code changes |
 | **diff** | comparison | Data teams understand diff from git/version control |
+| **artifacts** | build outputs | dbt manifest.json, catalog.json files |
+| **run dbt** | execute dbt, build models | Preferred: "run dbt" not "execute" or "build" |
+| **materialization** | table creation strategy | How dbt creates tables (table, view, incremental) |
+| **dbt target** | environment config | profiles.yml target configuration |
+| **warehouse connection** | database connection | Data team context for connecting to warehouse |
+| **development workspace** | dev environment | Where data analysts work on models |
+| **production workspace** | prod environment | Live data warehouse with production data |
 
 ### Business Impact Language
 
@@ -47,6 +63,11 @@ This guide helps maintain consistent, data-team-friendly language across all Rec
 | **confident releases** | successful deployments | User empowerment over technical success |
 | **team collaboration** | workflow integration | People-first over tool-first |
 | **validate changes** | test modifications | Active validation vs passive testing |
+| **validation checklist** | test suite | Collaborative validation workflow for teams |
+| **share findings** | distribute results | Team collaboration on validation results |
+| **review together** | collaborate on validation | Team-based change review process |
+| **check status** | test results | Current state of validation checks |
+| **approve changes** | sign off on deployment | Business approval vs technical deployment |
 
 ## Terms That Confuse Data Teams
 
@@ -72,6 +93,16 @@ This guide helps maintain consistent, data-team-friendly language across all Rec
 - **Software team thinks**: Unit/integration tests for code
 - **✅ Use instead**: "validation" or "data quality checks"
 
+**Build**
+- **Data team thinks**: "dbt run" - executing transformations
+- **Software team thinks**: Compile/package application
+- **✅ Use instead**: "run models" or "execute transformations"
+
+**Server**
+- **Data team thinks**: Database server (Snowflake, BigQuery)
+- **Software team thinks**: Web server or application server
+- **✅ Use instead**: "Recce UI" or "Recce interface" for the tool
+
 ### ⚠️ Medium Confusion Terms
 
 **Model**
@@ -89,6 +120,21 @@ This guide helps maintain consistent, data-team-friendly language across all Rec
 - **Software context**: Deployment target or goal
 - **✅ Clarify**: "dbt target" when referring to profiles.yml
 
+**Artifacts**
+- **Data context**: dbt-generated metadata files (manifest.json, catalog.json)
+- **Software context**: Build outputs, compiled binaries
+- **✅ Clarify**: "dbt artifacts" or "metadata files"
+
+**Workspace**
+- **Data context**: Development area in data warehouse
+- **Software context**: IDE or development environment
+- **✅ Clarify**: "development workspace" vs "local workspace"
+
+**Instance**
+- **Data context**: Recce UI session or warehouse instance
+- **Software context**: Running application or server
+- **✅ Clarify**: "Recce session" or "warehouse connection"
+
 ## Terminology Alert System
 
 When reviewing documentation, flag confusing terms with this format:
@@ -141,6 +187,48 @@ While software teams deploy applications, data teams release model changes to th
 Configure your dbt target (the warehouse connection in profiles.yml) to point to your development environment.
 ```
 
+## Conflicting Usage Patterns
+
+These terms are used inconsistently across the documentation, creating potential confusion. Document conflicts here without changing the content immediately.
+
+### 🔀 Terms Used Inconsistently
+
+**"Environment" vs "Target" vs "Workspace"**
+- **Data team perspective**: "Target" refers to dbt profiles.yml config, "Environment" means warehouse type (Snowflake vs BigQuery)
+- **Software team perspective**: "Environment" means dev/staging/prod deployment context
+- **Current usage in docs**: Mixed usage - sometimes "environment" for dbt targets, sometimes for deployment stages
+- **Recommendation**: Use "dbt target" for profiles.yml, "development workspace" for where analysts work
+
+**"Check" vs "Validation" vs "Test"**
+- **Data team perspective**: "Validation" sounds more professional than "testing", "checks" are specific validations
+- **Software team perspective**: "Tests" are automated code verification, "checks" are CI/CD gates
+- **Current usage in docs**: Mixed - "preset checks", "validation workflow", "test your models"
+- **Recommendation**: Standardize on "validation" for data quality, "checks" for specific validation rules
+
+**"Build" vs "Run" vs "Execute"**
+- **Data team perspective**: "Run dbt" is the standard command, "build" sounds like compiling code
+- **Software team perspective**: "Build" means compile/package, "execute" means run program
+- **Current usage in docs**: Mixed usage - "build your models", "run dbt", "execute transformations"
+- **Recommendation**: Use "run" for dbt operations, avoid "build" and "execute"
+
+**"Review" vs "Audit" vs "Validation"**
+- **Data team perspective**: "Review" is collaborative, "audit" is formal compliance checking
+- **Software team perspective**: "Review" is code review process, "audit" is security scanning
+- **Current usage in docs**: "Review mode", "change review", "validation workflow"
+- **Recommendation**: Use "review" for collaborative processes, "validation" for automated checks
+
+**"Pipeline" vs "Workflow"**
+- **Data team perspective**: "Pipeline" means data transformation flow (dbt models)
+- **Software team perspective**: "Pipeline" means CI/CD automation pipeline
+- **Current usage in docs**: "CI/CD pipeline", "validation workflow", "automation workflow"
+- **Recommendation**: "Data pipeline" for transformations, "automation workflow" for CI/CD
+
+**"Deploy" vs "Release" vs "Publish"**
+- **Data team perspective**: "Release" means making changes live, "deploy" sounds like infrastructure
+- **Software team perspective**: "Deploy" means publish application, "release" means version release
+- **Current usage in docs**: Mixed - "deploy changes", "release changes", "publish results"
+- **Recommendation**: Use "release" for data changes, "deploy" only for infrastructure
+
 ## Maintenance Guidelines
 
 ### Adding New Terms
@@ -174,6 +262,11 @@ Before publishing, verify:
 | "Production deployment" | "Production release" | Making changes live |
 | "Development environment" | "Development warehouse" | Where you develop |
 | "Code review" | "Change review" | Reviewing data modifications |
+| "Build models" | "Run models" | dbt model execution |
+| "Execute dbt" | "Run dbt" | Standard dbt command usage |
+| "Check results" | "Validation status" | Status of data validation |
+| "Recce server" | "Recce interface" | The UI tool itself |
+| "Database connection" | "Warehouse connection" | Data team context |
 
 ---
 
diff --git a/claude/writing-principles.md b/claude/writing-principles.md
@@ -143,13 +143,12 @@ Avoid Uncertainty Language, like:
 Maintain consistency with the 9-section structure:
 1. **What's Recce** - Introduction, value proposition, use cases
 2. **Getting Started** - Installation, tutorials, first steps
-3. **View Modified** - Core functionality, diff analysis
+3. **Visualized Change** - Core functionality, diff analysis
 4. **Downstream Impacts** - Impact analysis, dependency mapping
 5. **Data Diffing** - Query comparison, validation techniques
 6. **Collaborate Validation** - Team workflows, checklist management
-7. **Workflow Integration** - CI/CD, automation, best practices
-8. **Lots Models** - Scale considerations, performance optimization
-9. **Technical Concepts** - Architecture, configuration, security
+7. **CI/CD** - CI/CD, automation, best practices
+8. **Technical Concepts** - Architecture, configuration
 
 These structure is to align users adoption process. Start from using in PR, colloaborate with team, and using in dev time. And know more technical behind it. 
 
