You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: projects/collector-docs-refactoring.md
+62-28Lines changed: 62 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,22 +2,38 @@
2
2
3
3
## Background and description
4
4
5
-
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.
5
+
The OpenTelemetry Collector is a critical component of the OpenTelemetry
6
+
ecosystem, serving as a vendor-agnostic way to receive, process, and export
7
+
telemetry data. The Collector documentation on
8
+
[opentelemetry.io](https://opentelemetry.io/docs/collector/) is currently
9
+
undergoing a significant refactoring effort to improve organization, clarity,
10
+
and completeness.
6
11
7
-
This project coordinates the ongoing refactoring of Collector documentation, which is being tracked through the `sig:collector:refactor` label and organized into multiple phases.
12
+
This project coordinates the ongoing refactoring of Collector documentation,
13
+
which is being tracked through the `sig:collector:refactor` label and organized
14
+
into multiple phases.
8
15
9
-
**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.
16
+
**Note**: This project is already underway with active issues and a milestone.
17
+
This document serves to formalize the project scope and track progress within
18
+
the community projects framework.
10
19
11
20
### Current challenges
12
21
13
22
The current Collector documentation has several issues being addressed:
14
23
15
-
-**Information architecture needs improvement**: Pages are not organized optimally for different user journeys (installation, deployment, configuration, extension).
16
-
-**Large monolithic pages**: Some pages (like installation) need to be split into focused child pages.
17
-
-**Inconsistent examples**: Examples sometimes use core vs. contrib inconsistently.
18
-
-**Missing operational guidance**: Best practices, troubleshooting, and disaster recovery documentation is incomplete.
19
-
-**Copy editing needed**: Many pages need style guide compliance, grammar fixes, and clarity improvements.
20
-
-**Cross-reference maintenance**: Page renames require updating cross-references throughout the documentation.
24
+
-**Information architecture needs improvement**: Pages are not organized
25
+
optimally for different user journeys (installation, deployment,
26
+
configuration, extension).
27
+
-**Large monolithic pages**: Some pages (like installation) need to be split
28
+
into focused child pages.
29
+
-**Inconsistent examples**: Examples sometimes use core vs. contrib
30
+
inconsistently.
31
+
-**Missing operational guidance**: Best practices, troubleshooting, and
32
+
disaster recovery documentation is incomplete.
33
+
-**Copy editing needed**: Many pages need style guide compliance, grammar
**Current structure verified in repository (`content/en/docs/collector/`):**
23
39
@@ -56,6 +72,7 @@ collector/
56
72
```
57
73
58
74
**Progress on refactoring:**
75
+
59
76
- ✅ `building/` section exists with custom component guides
60
77
- ✅ `deployment/` section has agent, gateway, no-collector patterns
61
78
- ✅ `components/` section documents all component types
@@ -66,12 +83,17 @@ collector/
66
83
67
84
The goal of this project is to:
68
85
69
-
1.**Restructure information architecture**: Create a logical hierarchy (Install, Deploy, Extend sections).
70
-
2.**Split large pages**: Break monolithic pages into focused, scannable content.
71
-
3.**Standardize examples**: Ensure consistent use of Collector distributions in examples.
72
-
4.**Add operational content**: Include best practices, troubleshooting, and scaling documentation.
86
+
1.**Restructure information architecture**: Create a logical hierarchy
87
+
(Install, Deploy, Extend sections).
88
+
2.**Split large pages**: Break monolithic pages into focused, scannable
89
+
content.
90
+
3.**Standardize examples**: Ensure consistent use of Collector distributions in
91
+
examples.
92
+
4.**Add operational content**: Include best practices, troubleshooting, and
93
+
scaling documentation.
73
94
5.**Copy edit all pages**: Ensure style guide compliance and clear writing.
74
-
6.**Maintain cross-references**: Update all links when pages are renamed or moved.
95
+
6.**Maintain cross-references**: Update all links when pages are renamed or
96
+
moved.
75
97
76
98
## Deliverables
77
99
@@ -117,24 +139,36 @@ Gap analysis of the new documentation set:
117
139
118
140
### Phase 1 issues (otelcol-phase-1 milestone)
119
141
120
-
-[#8353 - Rename and split up Collector installation page](https://github.com/open-telemetry/opentelemetry.io/issues/8353) (open)
121
-
-[#8354 - Copy edit the Collector installation page](https://github.com/open-telemetry/opentelemetry.io/issues/8354) (open)
122
-
-[#8355 - Rename Collector deployment pages and create new child pages](https://github.com/open-telemetry/opentelemetry.io/issues/8355) (open)
123
-
-[#8356 - Copy edit the Collector deployment landing, no collector, and agent pages](https://github.com/open-telemetry/opentelemetry.io/issues/8356) (closed)
124
-
-[#8358 - Copy edit the Collector deployment gateway page](https://github.com/open-telemetry/opentelemetry.io/issues/8358) (closed)
125
-
-[#8360 - Create new "Extend the Collector" section and rename child pages](https://github.com/open-telemetry/opentelemetry.io/issues/8360) (open)
126
-
-[#8361 - Copy edit the Building a custom Collector page](https://github.com/open-telemetry/opentelemetry.io/issues/8361) (open)
127
-
-[#8362 - Copy edit the custom component pages](https://github.com/open-telemetry/opentelemetry.io/issues/8362) (open)
142
+
-[#8353 - Rename and split up Collector installation page](https://github.com/open-telemetry/opentelemetry.io/issues/8353)
143
+
(open)
144
+
-[#8354 - Copy edit the Collector installation page](https://github.com/open-telemetry/opentelemetry.io/issues/8354)
145
+
(open)
146
+
-[#8355 - Rename Collector deployment pages and create new child pages](https://github.com/open-telemetry/opentelemetry.io/issues/8355)
147
+
(open)
148
+
-[#8356 - Copy edit the Collector deployment landing, no collector, and agent pages](https://github.com/open-telemetry/opentelemetry.io/issues/8356)
149
+
(closed)
150
+
-[#8358 - Copy edit the Collector deployment gateway page](https://github.com/open-telemetry/opentelemetry.io/issues/8358)
151
+
(closed)
152
+
-[#8360 - Create new "Extend the Collector" section and rename child pages](https://github.com/open-telemetry/opentelemetry.io/issues/8360)
153
+
(open)
154
+
-[#8361 - Copy edit the Building a custom Collector page](https://github.com/open-telemetry/opentelemetry.io/issues/8361)
155
+
(open)
156
+
-[#8362 - Copy edit the custom component pages](https://github.com/open-telemetry/opentelemetry.io/issues/8362)
157
+
(open)
128
158
129
159
### Phase 3 issues (otelcol-phase-3 milestone)
130
160
131
-
-[#5932 - Disaster recovery recommendations for Daemonset deployments](https://github.com/open-telemetry/opentelemetry.io/issues/5932) (open)
132
-
-[#2692 - Follow up on collector deployment](https://github.com/open-telemetry/opentelemetry.io/issues/2692) (open)
161
+
-[#5932 - Disaster recovery recommendations for Daemonset deployments](https://github.com/open-telemetry/opentelemetry.io/issues/5932)
162
+
(open)
163
+
-[#2692 - Follow up on collector deployment](https://github.com/open-telemetry/opentelemetry.io/issues/2692)
164
+
(open)
133
165
134
166
### Other related issues
135
167
136
-
-[#7268 - Add example for validating internal telemetry connection](https://github.com/open-telemetry/opentelemetry.io/issues/7268) (open)
Copy file name to clipboardExpand all lines: projects/docs-automation-cicd.md
+69-29Lines changed: 69 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,19 +2,36 @@
2
2
3
3
## Background and description
4
4
5
-
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.
5
+
The OpenTelemetry documentation website relies on various automated processes
6
+
for building, validating, and maintaining content. However, several manual
7
+
processes remain, and existing automation has limitations that cause maintenance
8
+
burden and occasional build failures.
6
9
7
-
This project aims to enhance documentation automation, improve CI/CD pipelines, and implement systems for tracking documentation freshness and detecting outdated content.
10
+
This project aims to enhance documentation automation, improve CI/CD pipelines,
11
+
and implement systems for tracking documentation freshness and detecting
12
+
outdated content.
8
13
9
14
### Current challenges
10
15
11
16
The current documentation automation has several gaps:
12
17
13
-
-**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.
14
-
-**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.
15
-
-**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.
16
-
-**Missing mdatagen integration**: The `mdatagen` tool generates documentation for Collector components, but this isn't integrated into the website documentation pipeline.
17
-
-**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.
18
+
-**Manual Collector metrics maintenance**: The list of Collector internal
19
+
metrics on the website is manually maintained and can become out of sync with
20
+
the actual metrics generated by `mdatagen`. This leads to incomplete or
21
+
inaccurate documentation.
22
+
-**Version update automation issues**: The automated version update process for
23
+
Collector releases can break builds when patch releases don't include all
24
+
components (e.g., Collector Builder or Supervisor). The `cascade` field in
25
+
Hugo front matter causes issues with partial releases.
26
+
-**No automated outdated content detection**: There's no systematic way to
27
+
identify documentation that has become stale or needs updating. Content can
28
+
remain outdated for extended periods without maintainer awareness.
29
+
-**Missing mdatagen integration**: The `mdatagen` tool generates documentation
30
+
for Collector components, but this isn't integrated into the website
31
+
documentation pipeline.
32
+
-**Limited pre-commit checks**: Contributors may submit PRs that fail CI checks
33
+
because there are no local pre-commit hooks to catch common issues before
34
+
pushing.
18
35
19
36
**Existing automation verified in repository (`scripts/`):**
20
37
@@ -38,6 +55,7 @@ scripts/
38
55
```
39
56
40
57
**Gap analysis:**
58
+
41
59
- ✅ Version update scripts exist but have issues with patch releases
42
60
- ⚠️ Pre-commit hook exists but is minimal (only formatting)
43
61
- ⚠️ Markdown rules exist but not integrated with pre-commit
@@ -56,38 +74,53 @@ If these challenges are not addressed:
56
74
57
75
The goal of this project is to:
58
76
59
-
1.**Automate Collector metrics documentation**: Integrate mdatagen output into the website.
60
-
2.**Fix version update automation**: Handle patch releases correctly without breaking builds.
61
-
3.**Detect outdated content**: Implement systems to identify stale documentation.
62
-
4.**Improve contributor experience**: Add pre-commit hooks and local validation tools.
63
-
5.**Track documentation freshness**: Create visibility into documentation age and update needs.
77
+
1.**Automate Collector metrics documentation**: Integrate mdatagen output into
78
+
the website.
79
+
2.**Fix version update automation**: Handle patch releases correctly without
80
+
breaking builds.
81
+
3.**Detect outdated content**: Implement systems to identify stale
82
+
documentation.
83
+
4.**Improve contributor experience**: Add pre-commit hooks and local validation
84
+
tools.
85
+
5.**Track documentation freshness**: Create visibility into documentation age
86
+
and update needs.
64
87
65
88
**Motivations for starting now**:
66
89
67
-
- The Collector documentation refactoring project (sig:collector:refactor) would benefit from automated tooling.
68
-
- Recent build failures from patch releases highlight the urgency of fixing version automation.
90
+
- The Collector documentation refactoring project (sig:collector:refactor) would
91
+
benefit from automated tooling.
92
+
- Recent build failures from patch releases highlight the urgency of fixing
93
+
version automation.
69
94
- Community feedback indicates that outdated content is a significant problem.
70
95
71
96
## Deliverables
72
97
73
98
### mdatagen integration
74
99
75
-
-**Automated metrics documentation**: Pipeline to extract and publish Collector component metrics from mdatagen.
76
-
-**Component documentation sync**: Automated sync of component READMEs to website.
77
-
-**Stability level tracking**: Automated tracking and display of component stability levels.
100
+
-**Automated metrics documentation**: Pipeline to extract and publish Collector
101
+
component metrics from mdatagen.
102
+
-**Component documentation sync**: Automated sync of component READMEs to
103
+
website.
104
+
-**Stability level tracking**: Automated tracking and display of component
105
+
stability levels.
78
106
79
107
### Version automation improvements
80
108
81
-
-**Patch release handling**: Fix the cascade version update mechanism to handle partial releases.
82
-
-**Component-specific versioning**: Separate version tracking for Collector core, contrib, Builder, and Supervisor.
83
-
-**Release notes integration**: Automated linking to release notes for each version.
109
+
-**Patch release handling**: Fix the cascade version update mechanism to handle
110
+
partial releases.
111
+
-**Component-specific versioning**: Separate version tracking for Collector
112
+
core, contrib, Builder, and Supervisor.
113
+
-**Release notes integration**: Automated linking to release notes for each
114
+
version.
84
115
85
116
### Outdated content detection
86
117
87
118
-**Content age tracking**: System to track when content was last updated.
88
-
-**Drift detection alerts**: Automated notifications when content hasn't been updated within a threshold.
119
+
-**Drift detection alerts**: Automated notifications when content hasn't been
120
+
updated within a threshold.
89
121
-**External link validation**: Regular checks for broken external links.
90
-
-**API/SDK version comparisons**: Alerts when documented versions fall behind latest releases.
122
+
-**API/SDK version comparisons**: Alerts when documented versions fall behind
123
+
latest releases.
91
124
92
125
### Contributor tooling
93
126
@@ -101,9 +134,12 @@ The goal of this project is to:
101
134
102
135
### Freshness tracking
103
136
104
-
-**Documentation freshness dashboard**: Visibility into documentation age across sections.
105
-
-**Update priority scoring**: System to prioritize which content needs updates most urgently.
106
-
-**Maintainer notifications**: Automated notifications for high-priority updates.
137
+
-**Documentation freshness dashboard**: Visibility into documentation age
138
+
across sections.
139
+
-**Update priority scoring**: System to prioritize which content needs updates
140
+
most urgently.
141
+
-**Maintainer notifications**: Automated notifications for high-priority
142
+
updates.
107
143
108
144
## Timeline
109
145
@@ -122,17 +158,21 @@ The goal of this project is to:
122
158
123
159
## Related issues
124
160
125
-
-[#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.
126
-
-[#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.
127
-
-[#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.
161
+
-[#4523 - Automate the Collector list of internal metrics using `mdatagen` docs](https://github.com/open-telemetry/opentelemetry.io/issues/4523)
162
+
(open) - mdatagen integration for metrics documentation.
163
+
-[#7546 - Collector patch release updates break build because not all components are included](https://github.com/open-telemetry/opentelemetry.io/issues/7546)
164
+
(open) - Version automation issues.
165
+
-[#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)
166
+
(open) - Pre-commit hooks using husky.
128
167
129
168
## Project Board
130
169
131
170
To be created upon project approval.
132
171
133
172
## SIG Meetings and Other Info
134
173
135
-
This project will be coordinated through SIG Communications meetings with input from SIG Collector.
174
+
This project will be coordinated through SIG Communications meetings with input
175
+
from SIG Collector.
136
176
137
177
-**Slack channel**: `#otel-comms`
138
178
-**Meeting notes**: To be linked upon project start.
0 commit comments