Fix all

Author: theletterf

projects/collector-docs-refactoring.md

@@ -2,22 +2,38 @@
 
 ## Background and description
 
-The OpenTelemetry Collector is a critical component of the OpenTelemetry ecosystem, serving as a vendor-agnostic way to receive, process, and export telemetry data. The Collector documentation on [opentelemetry.io](https://opentelemetry.io/docs/collector/) is currently undergoing a significant refactoring effort to improve organization, clarity, and completeness.
+The OpenTelemetry Collector is a critical component of the OpenTelemetry
+ecosystem, serving as a vendor-agnostic way to receive, process, and export
+telemetry data. The Collector documentation on
+[opentelemetry.io](https://opentelemetry.io/docs/collector/) is currently
+undergoing a significant refactoring effort to improve organization, clarity,
+and completeness.
 
-This project coordinates the ongoing refactoring of Collector documentation, which is being tracked through the `sig:collector:refactor` label and organized into multiple phases.
+This project coordinates the ongoing refactoring of Collector documentation,
+which is being tracked through the `sig:collector:refactor` label and organized
+into multiple phases.
 
-**Note**: This project is already underway with active issues and a milestone. This document serves to formalize the project scope and track progress within the community projects framework.
+**Note**: This project is already underway with active issues and a milestone.
+This document serves to formalize the project scope and track progress within
+the community projects framework.
 
 ### Current challenges
 
 The current Collector documentation has several issues being addressed:
 
-- **Information architecture needs improvement**: Pages are not organized optimally for different user journeys (installation, deployment, configuration, extension).
-- **Large monolithic pages**: Some pages (like installation) need to be split into focused child pages.
-- **Inconsistent examples**: Examples sometimes use core vs. contrib inconsistently.
-- **Missing operational guidance**: Best practices, troubleshooting, and disaster recovery documentation is incomplete.
-- **Copy editing needed**: Many pages need style guide compliance, grammar fixes, and clarity improvements.
-- **Cross-reference maintenance**: Page renames require updating cross-references throughout the documentation.
+- **Information architecture needs improvement**: Pages are not organized
+  optimally for different user journeys (installation, deployment,
+  configuration, extension).
+- **Large monolithic pages**: Some pages (like installation) need to be split
+  into focused child pages.
+- **Inconsistent examples**: Examples sometimes use core vs. contrib
+  inconsistently.
+- **Missing operational guidance**: Best practices, troubleshooting, and
+  disaster recovery documentation is incomplete.
+- **Copy editing needed**: Many pages need style guide compliance, grammar
+  fixes, and clarity improvements.
+- **Cross-reference maintenance**: Page renames require updating
+  cross-references throughout the documentation.
 
 **Current structure verified in repository (`content/en/docs/collector/`):**
 
@@ -56,6 +72,7 @@ collector/
 ```
 
 **Progress on refactoring:**
+
 - ✅ `building/` section exists with custom component guides
 - ✅ `deployment/` section has agent, gateway, no-collector patterns
 - ✅ `components/` section documents all component types
@@ -66,12 +83,17 @@ collector/
 
 The goal of this project is to:
 
-1. **Restructure information architecture**: Create a logical hierarchy (Install, Deploy, Extend sections).
-2. **Split large pages**: Break monolithic pages into focused, scannable content.
-3. **Standardize examples**: Ensure consistent use of Collector distributions in examples.
-4. **Add operational content**: Include best practices, troubleshooting, and scaling documentation.
+1. **Restructure information architecture**: Create a logical hierarchy
+   (Install, Deploy, Extend sections).
+2. **Split large pages**: Break monolithic pages into focused, scannable
+   content.
+3. **Standardize examples**: Ensure consistent use of Collector distributions in
+   examples.
+4. **Add operational content**: Include best practices, troubleshooting, and
+   scaling documentation.
 5. **Copy edit all pages**: Ensure style guide compliance and clear writing.
-6. **Maintain cross-references**: Update all links when pages are renamed or moved.
+6. **Maintain cross-references**: Update all links when pages are renamed or
+   moved.
 
 ## Deliverables
 
@@ -117,24 +139,36 @@ Gap analysis of the new documentation set:
 
 ### Phase 1 issues (otelcol-phase-1 milestone)
 
-- [#8353 - Rename and split up Collector installation page](https://github.com/open-telemetry/opentelemetry.io/issues/8353) (open)
-- [#8354 - Copy edit the Collector installation page](https://github.com/open-telemetry/opentelemetry.io/issues/8354) (open)
-- [#8355 - Rename Collector deployment pages and create new child pages](https://github.com/open-telemetry/opentelemetry.io/issues/8355) (open)
-- [#8356 - Copy edit the Collector deployment landing, no collector, and agent pages](https://github.com/open-telemetry/opentelemetry.io/issues/8356) (closed)
-- [#8358 - Copy edit the Collector deployment gateway page](https://github.com/open-telemetry/opentelemetry.io/issues/8358) (closed)
-- [#8360 - Create new "Extend the Collector" section and rename child pages](https://github.com/open-telemetry/opentelemetry.io/issues/8360) (open)
-- [#8361 - Copy edit the Building a custom Collector page](https://github.com/open-telemetry/opentelemetry.io/issues/8361) (open)
-- [#8362 - Copy edit the custom component pages](https://github.com/open-telemetry/opentelemetry.io/issues/8362) (open)
+- [#8353 - Rename and split up Collector installation page](https://github.com/open-telemetry/opentelemetry.io/issues/8353)
+  (open)
+- [#8354 - Copy edit the Collector installation page](https://github.com/open-telemetry/opentelemetry.io/issues/8354)
+  (open)
+- [#8355 - Rename Collector deployment pages and create new child pages](https://github.com/open-telemetry/opentelemetry.io/issues/8355)
+  (open)
+- [#8356 - Copy edit the Collector deployment landing, no collector, and agent pages](https://github.com/open-telemetry/opentelemetry.io/issues/8356)
+  (closed)
+- [#8358 - Copy edit the Collector deployment gateway page](https://github.com/open-telemetry/opentelemetry.io/issues/8358)
+  (closed)
+- [#8360 - Create new "Extend the Collector" section and rename child pages](https://github.com/open-telemetry/opentelemetry.io/issues/8360)
+  (open)
+- [#8361 - Copy edit the Building a custom Collector page](https://github.com/open-telemetry/opentelemetry.io/issues/8361)
+  (open)
+- [#8362 - Copy edit the custom component pages](https://github.com/open-telemetry/opentelemetry.io/issues/8362)
+  (open)
 
 ### Phase 3 issues (otelcol-phase-3 milestone)
 
-- [#5932 - Disaster recovery recommendations for Daemonset deployments](https://github.com/open-telemetry/opentelemetry.io/issues/5932) (open)
-- [#2692 - Follow up on collector deployment](https://github.com/open-telemetry/opentelemetry.io/issues/2692) (open)
+- [#5932 - Disaster recovery recommendations for Daemonset deployments](https://github.com/open-telemetry/opentelemetry.io/issues/5932)
+  (open)
+- [#2692 - Follow up on collector deployment](https://github.com/open-telemetry/opentelemetry.io/issues/2692)
+  (open)
 
 ### Other related issues
 
-- [#7268 - Add example for validating internal telemetry connection](https://github.com/open-telemetry/opentelemetry.io/issues/7268) (open)
-- [#3699 - Benchmarks page clarity](https://github.com/open-telemetry/opentelemetry.io/issues/3699) (open)
+- [#7268 - Add example for validating internal telemetry connection](https://github.com/open-telemetry/opentelemetry.io/issues/7268)
+  (open)
+- [#3699 - Benchmarks page clarity](https://github.com/open-telemetry/opentelemetry.io/issues/3699)
+  (open)
 
 ## Project Board
 
@@ -145,8 +179,8 @@ The project is tracked via GitHub milestones:
 
 ## SIG Meetings and Other Info
 
-This project is coordinated through SIG Communications and SIG Collector meetings.
+This project is coordinated through SIG Communications and SIG Collector
+meetings.
 
 - **Slack channel**: `#otel-comms`
 - **Meeting notes**: To be linked upon project start.
-

projects/docs-automation-cicd.md

@@ -2,19 +2,36 @@
 
 ## Background and description
 
-The OpenTelemetry documentation website relies on various automated processes for building, validating, and maintaining content. However, several manual processes remain, and existing automation has limitations that cause maintenance burden and occasional build failures.
+The OpenTelemetry documentation website relies on various automated processes
+for building, validating, and maintaining content. However, several manual
+processes remain, and existing automation has limitations that cause maintenance
+burden and occasional build failures.
 
-This project aims to enhance documentation automation, improve CI/CD pipelines, and implement systems for tracking documentation freshness and detecting outdated content.
+This project aims to enhance documentation automation, improve CI/CD pipelines,
+and implement systems for tracking documentation freshness and detecting
+outdated content.
 
 ### Current challenges
 
 The current documentation automation has several gaps:
 
-- **Manual Collector metrics maintenance**: The list of Collector internal metrics on the website is manually maintained and can become out of sync with the actual metrics generated by `mdatagen`. This leads to incomplete or inaccurate documentation.
-- **Version update automation issues**: The automated version update process for Collector releases can break builds when patch releases don't include all components (e.g., Collector Builder or Supervisor). The `cascade` field in Hugo front matter causes issues with partial releases.
-- **No automated outdated content detection**: There's no systematic way to identify documentation that has become stale or needs updating. Content can remain outdated for extended periods without maintainer awareness.
-- **Missing mdatagen integration**: The `mdatagen` tool generates documentation for Collector components, but this isn't integrated into the website documentation pipeline.
-- **Limited pre-commit checks**: Contributors may submit PRs that fail CI checks because there are no local pre-commit hooks to catch common issues before pushing.
+- **Manual Collector metrics maintenance**: The list of Collector internal
+  metrics on the website is manually maintained and can become out of sync with
+  the actual metrics generated by `mdatagen`. This leads to incomplete or
+  inaccurate documentation.
+- **Version update automation issues**: The automated version update process for
+  Collector releases can break builds when patch releases don't include all
+  components (e.g., Collector Builder or Supervisor). The `cascade` field in
+  Hugo front matter causes issues with partial releases.
+- **No automated outdated content detection**: There's no systematic way to
+  identify documentation that has become stale or needs updating. Content can
+  remain outdated for extended periods without maintainer awareness.
+- **Missing mdatagen integration**: The `mdatagen` tool generates documentation
+  for Collector components, but this isn't integrated into the website
+  documentation pipeline.
+- **Limited pre-commit checks**: Contributors may submit PRs that fail CI checks
+  because there are no local pre-commit hooks to catch common issues before
+  pushing.
 
 **Existing automation verified in repository (`scripts/`):**
 
@@ -38,6 +55,7 @@ scripts/
 ```
 
 **Gap analysis:**
+
 - ✅ Version update scripts exist but have issues with patch releases
 - ⚠️ Pre-commit hook exists but is minimal (only formatting)
 - ⚠️ Markdown rules exist but not integrated with pre-commit
@@ -56,38 +74,53 @@ If these challenges are not addressed:
 
 The goal of this project is to:
 
-1. **Automate Collector metrics documentation**: Integrate mdatagen output into the website.
-2. **Fix version update automation**: Handle patch releases correctly without breaking builds.
-3. **Detect outdated content**: Implement systems to identify stale documentation.
-4. **Improve contributor experience**: Add pre-commit hooks and local validation tools.
-5. **Track documentation freshness**: Create visibility into documentation age and update needs.
+1. **Automate Collector metrics documentation**: Integrate mdatagen output into
+   the website.
+2. **Fix version update automation**: Handle patch releases correctly without
+   breaking builds.
+3. **Detect outdated content**: Implement systems to identify stale
+   documentation.
+4. **Improve contributor experience**: Add pre-commit hooks and local validation
+   tools.
+5. **Track documentation freshness**: Create visibility into documentation age
+   and update needs.
 
 **Motivations for starting now**:
 
-- The Collector documentation refactoring project (sig:collector:refactor) would benefit from automated tooling.
-- Recent build failures from patch releases highlight the urgency of fixing version automation.
+- The Collector documentation refactoring project (sig:collector:refactor) would
+  benefit from automated tooling.
+- Recent build failures from patch releases highlight the urgency of fixing
+  version automation.
 - Community feedback indicates that outdated content is a significant problem.
 
 ## Deliverables
 
 ### mdatagen integration
 
-- **Automated metrics documentation**: Pipeline to extract and publish Collector component metrics from mdatagen.
-- **Component documentation sync**: Automated sync of component READMEs to website.
-- **Stability level tracking**: Automated tracking and display of component stability levels.
+- **Automated metrics documentation**: Pipeline to extract and publish Collector
+  component metrics from mdatagen.
+- **Component documentation sync**: Automated sync of component READMEs to
+  website.
+- **Stability level tracking**: Automated tracking and display of component
+  stability levels.
 
 ### Version automation improvements
 
-- **Patch release handling**: Fix the cascade version update mechanism to handle partial releases.
-- **Component-specific versioning**: Separate version tracking for Collector core, contrib, Builder, and Supervisor.
-- **Release notes integration**: Automated linking to release notes for each version.
+- **Patch release handling**: Fix the cascade version update mechanism to handle
+  partial releases.
+- **Component-specific versioning**: Separate version tracking for Collector
+  core, contrib, Builder, and Supervisor.
+- **Release notes integration**: Automated linking to release notes for each
+  version.
 
 ### Outdated content detection
 
 - **Content age tracking**: System to track when content was last updated.
-- **Drift detection alerts**: Automated notifications when content hasn't been updated within a threshold.
+- **Drift detection alerts**: Automated notifications when content hasn't been
+  updated within a threshold.
 - **External link validation**: Regular checks for broken external links.
-- **API/SDK version comparisons**: Alerts when documented versions fall behind latest releases.
+- **API/SDK version comparisons**: Alerts when documented versions fall behind
+  latest releases.
 
 ### Contributor tooling
 
@@ -101,9 +134,12 @@ The goal of this project is to:
 
 ### Freshness tracking
 
-- **Documentation freshness dashboard**: Visibility into documentation age across sections.
-- **Update priority scoring**: System to prioritize which content needs updates most urgently.
-- **Maintainer notifications**: Automated notifications for high-priority updates.
+- **Documentation freshness dashboard**: Visibility into documentation age
+  across sections.
+- **Update priority scoring**: System to prioritize which content needs updates
+  most urgently.
+- **Maintainer notifications**: Automated notifications for high-priority
+  updates.
 
 ## Timeline
 
@@ -122,17 +158,21 @@ The goal of this project is to:
 
 ## Related issues
 
-- [#4523 - Automate the Collector list of internal metrics using `mdatagen` docs](https://github.com/open-telemetry/opentelemetry.io/issues/4523) (open) - mdatagen integration for metrics documentation.
-- [#7546 - Collector patch release updates break build because not all components are included](https://github.com/open-telemetry/opentelemetry.io/issues/7546) (open) - Version automation issues.
-- [#8313 - Set up git pre-commit and other hooks to make for a smoother contributor experience](https://github.com/open-telemetry/opentelemetry.io/issues/8313) (open) - Pre-commit hooks using husky.
+- [#4523 - Automate the Collector list of internal metrics using `mdatagen` docs](https://github.com/open-telemetry/opentelemetry.io/issues/4523)
+  (open) - mdatagen integration for metrics documentation.
+- [#7546 - Collector patch release updates break build because not all components are included](https://github.com/open-telemetry/opentelemetry.io/issues/7546)
+  (open) - Version automation issues.
+- [#8313 - Set up git pre-commit and other hooks to make for a smoother contributor experience](https://github.com/open-telemetry/opentelemetry.io/issues/8313)
+  (open) - Pre-commit hooks using husky.
 
 ## Project Board
 
 To be created upon project approval.
 
 ## SIG Meetings and Other Info
 
-This project will be coordinated through SIG Communications meetings with input from SIG Collector.
+This project will be coordinated through SIG Communications meetings with input
+from SIG Collector.
 
 - **Slack channel**: `#otel-comms`
 - **Meeting notes**: To be linked upon project start.