docs: refine workflow documentation and fix issue creation references

EdwardAngert · EdwardAngert · commit 807f9f279562 · 2025-04-24T14:27:52.000-04:00
- Update documentation to accurately reflect issue creation is planned but not implemented
- Rename OPTIMIZED-WORKFLOW.md to WORKFLOW-ARCHITECTURE.md for clarity
- Remove confusing terminology like 'optimized' and 'improved'
- Fix inconsistencies between architecture diagram and implementation
diff --git a/.github/docs/README.md b/.github/docs/README.md
@@ -88,7 +88,7 @@ The documentation workflow system has a clear separation of concerns with multip
 │  │   creation/update│  │   merges to main│  │   on schedule  │  │   PR      │ │
 │  │ • Generates     │  │ • Checks links  │  │ • Comprehensive │  │ • Basic   │ │
 │  │   preview links │  │   only          │  │   validation    │  │   checks  │ │
-│  │ • Validates docs│  │ • Falls back to │  │ • Creates issues│  │ • Fast    │ │
+│  │ • Validates docs│  │ • Falls back to │  │ • Planned: issues│  │ • Fast    │ │
 │  │ • Posts comments│  │   original doc  │  │   for problems  │  │   feedback│ │
 │  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  └─────┬─────┘ │
 │           │                    │                    │                  │       │
@@ -236,7 +236,7 @@ check-xrefs: true     # Comprehensive checks
 lint-vale: false      # Style not critical for weekly checks
 gen-preview: false    # No preview needed
 post-comment: false   # No PR to comment on
-create-issues: true   # Create issues for persistent problems
+create-issues: false  # Issue creation feature is planned but not implemented yet
 fail-on-error: true   # Strict validation
 ```
 
diff --git a/.github/docs/WORKFLOW-ARCHITECTURE.md b/.github/docs/WORKFLOW-ARCHITECTURE.md
@@ -1,10 +1,10 @@
-# Optimized Documentation Workflow
+# Documentation Workflow Architecture
 
-This document explains the optimized documentation workflow architecture, which streamlines validation and preview processes for Coder's documentation.
+This document explains the documentation workflow architecture, which handles validation and preview processes for Coder's documentation.
 
 ## Architecture Overview
 
-The new architecture is designed with clear separation of concerns, improved error handling, and more efficient processing:
+The architecture is designed with clear separation of concerns, strong error handling, and efficient processing:
 
 ```
 ┌─ Workflow Entry Points ─────────────────────────────────┐
@@ -108,7 +108,7 @@ preset: 'post-merge'
 ```
 
 - Focuses on link and cross-reference validation
-- Creates GitHub issues for broken links
+- Notifies about broken links (issue creation planned)
 - No preview generation
 
 ### Weekly Preset
@@ -120,7 +120,7 @@ preset: 'weekly'
 
 - Comprehensive link checking of all documentation
 - Strict validation with failure on errors
-- Creates GitHub issues with detailed diagnostics
+- Planned feature: GitHub issues with detailed diagnostics
 
 ### CI Preset
 
@@ -133,34 +133,34 @@ preset: 'ci'
 - Minimal dependency requirements
 - Fails fast on errors
 
-## Key Improvements
+## Key Features
 
-### 1. Elimination of Duplication
+### 1. Centralized Architecture
 
 - Consolidated workflow architecture with single source of truth
 - Unified validation reporting and formatting
 - Centralized configuration management
 
-### 2. Improved Error Handling
+### 2. Robust Error Handling
 
 - Fault-tolerant file detection with multiple fallback mechanisms
 - Graceful degradation when steps fail
 - Detailed error reporting with fix guidance
 
-### 3. Optimized Performance
+### 3. Efficient Processing
 
 - Conditional dependency installation
 - Parallel validation where possible
 - Focused validation based on context
 
-### 4. Enhanced User Experience
+### 4. Developer-Friendly Interface
 
 - Rich PR comments with direct links to documentation changes
 - Collapsible sections for detailed information
 - Multiple notification channels
 - Always-present validation status section with guidance
 
-### 5. Better Maintainability
+### 5. Maintainable Design
 
 - Clear separation of concerns between components
 - Standardized interfaces between stages
@@ -173,7 +173,7 @@ preset: 'ci'
 ```yaml
 jobs:
   docs-check:
-    uses: ./.github/workflows/docs-unified-optimized.yaml
+    uses: ./.github/workflows/docs-unified.yaml
     with:
       preset: 'pr'
 ```
@@ -183,7 +183,7 @@ jobs:
 ```yaml
 jobs:
   docs-check:
-    uses: ./.github/workflows/docs-unified-optimized.yaml
+    uses: ./.github/workflows/docs-unified.yaml
     with:
       preset: 'pr'
       check-links: false  # Skip link checking for faster results
@@ -195,7 +195,7 @@ jobs:
 ```yaml
 jobs:
   docs-check:
-    uses: ./.github/workflows/docs-unified-optimized.yaml
+    uses: ./.github/workflows/docs-unified.yaml
     with:
       # Explicitly configure everything
       lint-markdown: true
diff --git a/.github/docs/actions/docs-core/action.yaml b/.github/docs/actions/docs-core/action.yaml
@@ -1206,7 +1206,7 @@ runs:
         WARNINGS=""
         FAILURES=""
         
-        # Group results by status with improved error handling
+        # Group results by status with robust error handling
         if [ "$RESULTS" != "[]" ] && [ -n "$RESULTS" ]; then
           # Check if RESULTS is valid JSON before parsing
           if echo "$RESULTS" | jq -e . >/dev/null 2>&1; then
