docs: update documentation workflow readme with comprehensive guide

EdwardAngert · EdwardAngert · commit 53bdc1f6ca85 · 2025-04-24T10:40:11.000-04:00
- Add clear description of workflow components and architecture
- Document the two-stage PR comment system
- Describe validation features in detail
- Add troubleshooting section for common issues
- Include section on future improvements
diff --git a/.github/docs/README.md b/.github/docs/README.md
@@ -52,9 +52,11 @@ brew install vale
 pnpm install
 ```
 
-## Workflow Architecture Overview
+# Coder Documentation Workflow System
 
-The documentation workflow has a clear separation of concerns with multiple layers:
+## Workflow Architecture
+
+The documentation workflow system has a clear separation of concerns with multiple layers:
 
 ```
 ┌─ Workflow Entry Points ─────────────────────────────────┐
@@ -86,232 +88,186 @@ The documentation workflow has a clear separation of concerns with multiple laye
 └──────────────────────────────────────────────────────────┘
 ```
 
-## Available Workflows
+## Documentation Workflow Components
 
-### Workflow Components
+### Entry Point Workflows
 
-1. **Entry Points**:
-   - `docs-preview.yaml`: Quick previews for PR changes
-   - `docs-link-check.yaml`: Post-merge validation focusing on link integrity 
-   - `weekly-docs.yaml`: Scheduled comprehensive checks
-   - `docs-ci.yaml`: Fast CI checks for formatting
+The system provides four specialized entry points for different validation scenarios:
 
-2. **Unified Reusable Workflow**:
-   - `docs-unified.yaml`: Central workflow with preset configurations
+1. **PR Preview (docs-preview.yaml)**
+   - Triggers on PR create/update when docs files change
+   - Performs comprehensive validation on documentation changes
+   - Generates preview links and posts PR comments with results
+   - Skips link checking for faster feedback
 
-3. **Core Implementation**:
-   - `docs-core/action.yaml`: Phase-based composite action
+2. **Post-Merge Validation (docs-link-check.yaml)**
+   - Runs after merges to main branch
+   - Lightweight check focused only on link integrity
+   - Ensures merged content maintains external link validity
 
-### Configuration Presets
+3. **Weekly Check (weekly-docs.yaml)**
+   - Scheduled run every Monday at 9 AM
+   - Comprehensive validation of documentation health
+   - Checks links, cross-references, markdown structure, and formatting
+   - Creates issues for persistent problems
 
-The workflow system includes standardized configuration presets for common scenarios:
+4. **CI Check (docs-ci.yaml)**
+   - Fast validation for continuous integration
+   - Focuses on formatting and structural issues
+   - Designed for rapid feedback
 
-```yaml
-# Basic usage for PRs
-jobs:
-  docs-check:
-    uses: ./.github/workflows/docs-unified.yaml
-    with:
-      preset: 'pr'  # Options: 'pr', 'post-merge', 'weekly', 'ci'
-```
+### Unified Workflow & Presets
 
-Each preset configures the workflow for specific use cases:
+All entry points use the central `docs-unified.yaml` workflow with different preset configurations:
 
-- **PR Preset**: Full validation with preview URLs and PR comments
-- **Post-Merge**: Link and cross-reference validation with GitHub issues
-- **Weekly**: Comprehensive checks with strict validation
-- **CI**: Rapid syntax checking with fast-fail behavior
+| Preset | Description | Main Validations |
+|--------|-------------|------------------|
+| `pr` | Complete validation for PRs | markdown, formatting, style, cross-references |
+| `post-merge` | Lightweight check after merge | links |
+| `weekly` | Scheduled health check | markdown, formatting, links, cross-references |
+| `ci` | Fast CI validation | markdown, formatting |
 
-### Advanced Usage
+These presets ensure consistent validation based on context without duplicating logic.
 
-You can combine presets with explicit overrides:
+## Validation Features
 
-```yaml
-jobs:
-  docs-check:
-    uses: ./.github/workflows/docs-unified.yaml
-    with:
-      preset: 'pr'
-      check-links: false  # Skip link checking for faster results
-      notification-channels: 'slack'  # Add Slack notifications
-```
+### Two-Stage PR Comment System
 
-Or configure everything explicitly:
+The PR workflow implements a two-stage comment system:
 
-```yaml
-jobs:
-  docs-check:
-    uses: ./.github/workflows/docs-unified.yaml
-    with:
-      # Validation options
-      lint-markdown: true
-      check-format: true
-      check-links: true
-      check-cross-references: true
-      lint-vale: false
-      
-      # Output options
-      generate-preview: true
-      post-comment: true
-      create-issues: false
-      fail-on-error: false
-      
-      # Notification options
-      notification-channels: 'github-issue'
-      issue-labels: 'documentation,urgent'
-```
+1. **Initial Comment (Immediate)**
+   - Posted immediately after checkout and setup
+   - Provides preview links while validation runs
+   - Displays a "Validation in progress" status
+   - Allows reviewers to immediately start reviewing documentation
 
-## Key Features
-
-### 1. Core Requirements Implementation
-
-The workflow fulfills key documentation requirements:
-
-- **Single Unified Workflow**: All docs checks consolidated into one workflow
-- **Smart Path-Based Triggering**: Only runs on docs-related changes
-- **Enhanced File Detection**: Uses tj-actions/changed-files with fallbacks
-- **Preview Links in PR Comments**: Links to `https://coder.com/docs/@$BRANCH_NAME`
-- **Manifest-Aware Navigation**: Detects changes in manifest.json and provides direct file links
-- **Changed File Previews**: Provides direct links to files with significant changes
-- **Lychee Link Checking**: Comprehensive link validation including cross-references
-- **Vale Style Checking**: Enforces documentation style guidelines
-- **Efficient Post-Merge Checks**: Only runs link integrity checks after merge
-
-### 2. Multi-Phase Architecture
-
-The docs-core action uses a phase-based approach for optimal efficiency:
-
-- **Phase 1**: Security and Configuration
-  - Environment validation and security setup
-  - Configuration processing with presets
-  - Tool requirements determination
-  - Context information extraction
-
-- **Phase 2**: File Detection
-  - Robust change detection with multiple fallback mechanisms
-  - Cross-reference tracking for moved/renamed files
-  - Manifest.json change detection for navigation updates
-
-- **Phases 3-4**: Validation
-  - Link checking with lychee
-  - Vale style validation
-  - Cross-reference integrity checking
-  - Markdown linting and formatting validation
-
-- **Phases 5-6**: Results Processing
-  - Unified results format
-  - Direct links to changed files in preview
-  - Rich formatting with guidance
-  - Always-present validation status
-
-- **Phase 7**: Notifications
-  - Multi-channel notification support
-  - Comprehensive error reporting
-
-### 3. PR Comment Features
-
-When running with `post-comment: true`, the workflow posts a comprehensive PR comment containing:
-
-- **Status Overview**: Summary with clear status indicators (✅, ⚠️, ❌)
-- **Preview Links**: Direct links to documentation preview at `https://coder.com/docs/@$BRANCH_NAME`
-- **Changed File Links**: Direct links to specific changed files in the preview
-- **Manifest Navigation**: Links to files that have been moved or changed in manifest.json
-- **Validation Status**: Always-present section with common commands
-- **Issues Section**: Detailed breakdown with fix guidance (when issues exist)
-
-### 4. Unified Results Format
-
-All validation results use a standardized JSON structure:
-
-```json
-[
-  {
-    "name": "Markdown Linting",
-    "status": "success|failure|warning",
-    "message": "Summary of validation result",
-    "guidance": "Human-readable guidance on how to fix",
-    "fix_command": "Command to run to fix the issue"
-  }
-]
-```
+2. **Updated Comment (After Validation)**
+   - Updates the same comment with validation results
+   - Shows comprehensive validation status
+   - Includes direct links to changed files
+   - Provides validation statistics and duration information
+
+### Vale Style Checking
+
+The workflow includes Vale style checking that:
+- Only examines changed files to improve performance
+- Validates documentation against Coder style guidelines
+- Runs inline in the workflow (not as a separate action)
+- Is configured in `.github/docs/vale/` with custom rules
+
+### Link and Cross-Reference Verification
+
+Link checking features:
+- External link validation with lychee
+- Internal cross-reference verification
+- Configurable settings and ignore patterns in `.lycheeignore`
+- Special handling for manifest.json navigation changes
+
+### Markdown Validation
 
-### 5. Performance Optimizations
+The workflow validates markdown:
+- Structural issues (headings, lists, blockquotes)
+- Table formatting and alignment
+- Basic stylistic conventions
+- Document structure and organization
 
-- **Conditional Dependency Installation**: Only installs what's needed
-- **Parallel Validation**: Independent steps run concurrently
-- **Focused Validation**: Only runs necessary checks based on file changes
-- **Cross-Reference Efficiency**: Only checks relevant cross-references
-- **Post-Merge Optimization**: Skips redundant checks after merge to main
+## Workflow Configuration Options
+
+Each workflow entry point can be customized with these key parameters:
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `preset` | Predefined configuration bundle | (required) |
+| `lint-markdown` | Run markdown linting | (from preset) |
+| `check-format` | Validate table formatting | (from preset) |
+| `check-links` | Verify link integrity | (from preset) |
+| `check-cross-references` | Check documentation cross-references | (from preset) |
+| `lint-vale` | Run Vale style validation | (from preset) |
+| `generate-preview` | Create preview links | (from preset) |
+| `post-comment` | Post results as PR comment | (from preset) |
+| `create-issues` | Create GitHub issues for failures | (from preset) |
+| `fail-on-error` | Fail workflow on validation errors | (from preset) |
+
+## Future Improvements
+
+While the current documentation workflow system is robust and efficient, there are several areas for potential future enhancements:
+
+1. **Incremental Validation**
+   - Implement only checking files that have changed since the last validation
+   - Create a dependency graph of documentation files to optimize cross-reference checking
+
+2. **Advanced Link Checking**
+   - Add specialized handling for API endpoint references
+   - Implement schema validation for URLs in documentation
+   - Add validation for image references
+
+3. **Better Local Integration**
+   - Create a pre-commit hook that runs the same validation locally
+   - Develop a VSCode extension for real-time documentation validation
+
+4. **Enhanced Reporting**
+   - Implement trending analysis of documentation issues
+   - Add visualization of common problem areas
+   - Create a documentation quality dashboard
+
+5. **Automated Fixes**
+   - Implement auto-correction for common documentation issues
+   - Add AI-assisted suggestions for improvement
+
+6. **Integration with External Systems**
+   - Sync validation results with project management tools
+   - Implement notification integrations beyond GitHub and Slack
+
+By continuously improving the documentation workflow, we can maintain high-quality documentation while making the validation process more efficient for contributors.
 
 ## Troubleshooting
 
 ### Common Issues and Solutions
 
 #### File Detection Problems
 If changed files aren't being detected correctly:
-- The workflow includes robust fallback mechanisms
-- Default files will be used when detection fails
+- The workflow includes fallback mechanisms to ensure validation occurs
 - Check workflow logs for fallback notices
+- Verify you have changes in the docs/ directory
 
 #### Link Checking Errors
 If you see link checking errors:
-1. Run link checking locally with `lychee docs/**/*.md`
-2. Add legitimate failing links to `.github/docs/.lycheeignore`
-3. For internal cross-references, ensure anchors match headers exactly
-
-#### Cross-Reference Issues
-When files or headings are moved/renamed:
-1. The workflow automatically checks for broken cross-references in:
-   - Other documentation files 
-   - Code comments and strings throughout the codebase
-2. Fix any reported broken references by updating the links to point to the new location
-3. Use the validation results to identify which files reference the changed content
-
-#### Vale Style Issues
-If you see Vale style warnings:
-1. Check specific rules in the Vale output
-2. Use inline comments to disable specific rules: `<!-- vale StyleName.RuleName = NO -->`
+- Run link checking locally: `lychee docs/**/*.md`
+- Add exceptions to `.github/docs/.lycheeignore` if needed
+- For internal cross-references, ensure anchors match headers exactly
+
+#### Style Validation Issues
+If you encounter Vale style warnings:
+- Check specific rules in the output
+- Use inline comments to disable specific rules when appropriate:
+  `<!-- vale StyleName.RuleName = NO -->`
+- Consider updating the Vale style rules if the issue occurs frequently
 
 #### Preview URL Issues
-Preview URLs use a standardized format:
+The preview URL system converts branch names to URL-friendly format:
 - Branch names with slashes are converted to dashes
-- Use direct links from PR comments
 - Default links are provided even when no files change
+- The format is: `https://coder.com/docs/@<branch-name>`
 
-## Usage in Other Workflows
-
-If you need to incorporate documentation validation in other workflows:
-
-1. **Use the Unified Workflow**:
-   ```yaml
-   jobs:
-     docs-validation:
-       uses: ./.github/workflows/docs-unified.yaml
-       with:
-         preset: 'pr'  # or other preset based on context
-   ```
-
-2. **Use Configuration Presets**:
-   - `pr`: For pull request validation with preview links
-   - `post-merge`: For checking link integrity after merge
-   - `weekly`: For comprehensive scheduled checks
-   - `ci`: For fast checks during CI/CD pipelines
-
-3. **Extend with Custom Options** (if needed):
-   ```yaml
-   with:
-     preset: 'pr'
-     check-links: false  # Disable specific checks
-     create-issues: true  # Enable additional features
-   ```
+## Using Documentation Validation in Custom Workflows
 
-## Example Workflow Files
+To use documentation validation in your own workflows:
 
-For reference implementation, see these workflow files:
+```yaml
+jobs:
+  custom-docs-check:
+    uses: ./.github/workflows/docs-unified.yaml
+    with:
+      preset: 'pr'  # Choose a preset based on your needs
+      # Optional overrides
+      check-links: false  # For faster checks
+      notification-channels: 'slack'  # For notifications
+```
 
-- `docs-preview.yaml`: PR validation with preview links
-- `docs-link-check.yaml`: Post-merge link integrity checks
-- `weekly-docs.yaml`: Scheduled comprehensive validation
-- `docs-ci.yaml`: Fast CI checks for documentation formatting
+Available presets:
+- `pr`: Full validation with PR comments and preview links
+- `post-merge`: Lightweight link checking for merged content
+- `weekly`: Comprehensive health check for scheduled runs
+- `ci`: Fast validation for continuous integration
 
-For detailed workflow architecture documentation, see [OPTIMIZED-WORKFLOW.md](./OPTIMIZED-WORKFLOW.md).
+The presets provide sensible defaults for each use case, which can be overridden as needed for specific scenarios.
