Expand README for src/automated-pipelines (#58900)

Author: heiskr

src/automated-pipelines/README.md

@@ -53,3 +53,150 @@ Slack: `#docs-engineering`
 Repo: `github/docs-engineering`
 
 If you have a question about automation pipelines, you can ask in the `#docs-engineering` Slack channel. If you notice a problem with one of the automation pipelines, you can open an issue in the `github/docs-engineering` repository.
+
+## Sample Pipeline Template
+
+### Basic pipeline structure
+
+```
+src/<pipeline-name>/
+├── README.md                 # Pipeline documentation
+├── scripts/
+│   └── sync.ts              # Main sync script
+├── data/                    # Generated structured data (optional)
+│   ├── fpt/
+│   ├── ghec/
+│   └── ghes-*/
+├── lib/                     # Utilities and helpers
+├── components/              # React components (if needed)
+├── pages/                   # Next.js pages (if needed)
+└── tests/                   # Pipeline-specific tests
+### Minimal sync script example
+
+```typescript
+// scripts/sync.ts
+import { Command } from 'commander'
+
+const program = new Command()
+  .description('Sync <pipeline-name> data')
+  .option('--source-branch <branch>', 'Source repo branch', 'main')
+  .parse()
+
+const opts = program.opts()
+
+async function main() {
+  // 1. Fetch data from external source
+  // 2. Transform data
+  // 3. Write to data/ directory (or generate Markdown)
+  // 4. Validate output
+}
+
+main()
+```
+
+### Workflow example
+
+```yaml
+# .github/workflows/sync-<pipeline-name>.yml
+name: Sync <pipeline-name>
+
+on:
+  workflow_dispatch:
+    inputs:
+      SOURCE_BRANCH:
+        description: 'Branch to sync from'
+        default: 'main'
+  schedule:
+    - cron: '16 20 * * *'  # Daily
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm run sync-<pipeline-name>
+```
+
+## Ownership Table
+
+| Pipeline | Owning Team | Source Data Owner | Sync Frequency |
+|----------|-------------|-------------------|----------------|
+| REST | Docs Engineering | API Platform | Daily |
+| GraphQL | Docs Engineering | API Platform | Daily |
+| Webhooks | Docs Engineering | API Platform | Daily |
+| CodeQL CLI | Docs Engineering | Code Scanning | Per release |
+| GitHub Apps | Docs Engineering | Integrations | Daily |
+| Audit Logs | Docs Engineering | Enterprise | Daily |
+| Secret Scanning | Docs Engineering | Security | Daily |
+
+## Migration Status
+
+### Active pipelines (✅ Production)
+- REST API - Fully automated, daily sync
+- GraphQL API - Fully automated, daily sync
+- Webhooks - Fully automated, daily sync
+- GitHub Apps - Fully automated, daily sync
+- Secret Scanning - Fully automated, daily sync
+- Audit Logs - Fully automated, daily sync
+
+### Manual sync per release
+- CodeQL CLI - Manual sync per release
+
+### Legacy pipelines (📦 To migrate)
+- None currently identified
+
+### Migration patterns
+
+When migrating manual content to automated pipelines:
+1. **Audit existing content** - Document current structure
+2. **Source data analysis** - Identify gaps between source and docs
+3. **Data enrichment** - Work with source team to add missing fields
+4. **Scraping phase** - Temporarily scrape existing content to preserve prose
+5. **Gradual migration** - Migrate section by section
+6. **Validation** - Compare old vs new output
+7. **Deprecate manual** - Remove manual content once automated is stable
+
+## Shared Components
+
+Components in `src/automated-pipelines/components/` available for reuse:
+- Parameter tables
+- Response schemas
+- Code example formatting
+- Common layout patterns
+
+## Testing Strategy
+
+### Automated pipeline tests
+
+All autogenerated pages tested in `src/automated-pipelines/tests/rendering.ts`:
+- Page renders without errors
+- Required sections present
+- Links are valid
+- Schema validation
+
+### Pipeline-specific tests
+
+Each pipeline in `src/<pipeline-name>/tests/` should test:
+- Data transformation logic
+- Schema validation
+- Version handling
+- Edge cases specific to that pipeline
+
+### Testing locally
+
+```bash
+# Run all automated pipeline tests
+npm run test -- src/automated-pipelines/tests
+
+# Run specific pipeline tests
+npm run test -- src/<pipeline-name>/tests
+```
+
+We are not expecting significant investment here, but we will add and support pipelines as needed to meet business needs.
+
+### Developer experience
+- Pipeline scaffolding tool
+- Validation helpers
+- Testing fixtures
+- Documentation generator