diff --git a/projects/collector-docs-refactoring.md b/projects/collector-docs-refactoring.md new file mode 100644 index 000000000000..48aeafd2ab41 --- /dev/null +++ b/projects/collector-docs-refactoring.md @@ -0,0 +1,186 @@ +# Collector Documentation Refactoring + +## 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. + +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. + +### 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. + +**Current structure verified in repository (`content/en/docs/collector/`):** + +``` +collector/ +├── _index.md # Landing page +├── architecture.md # Architecture overview +├── benchmarks.md # Performance benchmarks +├── building/ # ✅ Custom collector building +│ ├── _index.md +│ ├── authenticator-extension.md +│ ├── connector/ +│ └── receiver.md +├── components/ # ✅ Component documentation +│ ├── connector.md +│ ├── exporter.md +│ ├── extension.md +│ ├── processor.md +│ └── receiver.md +├── configuration.md # Configuration reference +├── custom-collector.md # Custom collector guide +├── deployment/ # ✅ Deployment patterns +│ ├── _index.md +│ ├── agent.md +│ ├── gateway/ +│ └── no-collector.md +├── distributions.md # Distribution information +├── installation.md # Installation (needs splitting) +├── internal-telemetry.md # Internal metrics +├── management.md # OpAMP management +├── quick-start.md # Quick start guide +├── resiliency.md # Resiliency features +├── scaling.md # Scaling guide +├── transforming-telemetry.md +└── troubleshooting.md # Troubleshooting guide +``` + +**Progress on refactoring:** + +- ✅ `building/` section exists with custom component guides +- ✅ `deployment/` section has agent, gateway, no-collector patterns +- ✅ `components/` section documents all component types +- ⚠️ `installation.md` still monolithic (issue #8353) +- ⚠️ Troubleshooting exists but needs expansion + +### Goals, objectives, and requirements + +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. +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. + +## Deliverables + +### Phase 1 (otelcol-phase-1) - Current + +Focus on moving existing content to conform to the new information architecture: + +- Rename and split Collector installation page. +- Rename Collector deployment pages and create new child pages. +- Create new "Extend the Collector" section. +- Copy edit installation, deployment, and extension pages. +- Update cross-references throughout documentation. + +### Phase 2 (otelcol-phase-2) + +Focus on writing and editing content (details TBD based on Phase 1 completion). + +### Phase 3 (otelcol-phase-3) + +Gap analysis of the new documentation set: + +- Audit documentation for missing or incorrect content. +- Identify which examples to add first. +- Use AI, user interviews, and community feedback for analysis. +- Address disaster recovery recommendations. +- Follow up on deployment documentation improvements. + +## Timeline + +- **Phase 1**: Due December 31, 2025. +- **Phase 2**: TBD. +- **Phase 3**: Due March 20, 2026. + +## Labels + +- `sig:collector` +- `sig:collector:refactor` +- `docs:information-architecture` +- `help wanted` +- `good first issue` (for some tasks) + +## Related issues + +### 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) + +### 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) + +### 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) + +## Project Board + +The project is tracked via GitHub milestones: + +- [otelcol-phase-1](https://github.com/open-telemetry/opentelemetry.io/milestone/20) +- [otelcol-phase-3](https://github.com/open-telemetry/opentelemetry.io/milestone/22) + +## SIG Meetings and Other Info + +This project is coordinated through SIG Communications and SIG Collector +meetings. + +- **Slack channel**: `#otel-comms` +- **Meeting notes**: To be linked upon project start. diff --git a/projects/docs-automation-cicd.md b/projects/docs-automation-cicd.md new file mode 100644 index 000000000000..6f44fc0074c3 --- /dev/null +++ b/projects/docs-automation-cicd.md @@ -0,0 +1,178 @@ +# Documentation Automation and CI/CD Enhancement + +## 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. + +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. + +**Existing automation verified in repository (`scripts/`):** + +``` +scripts/ +├── auto-update/ # Version update scripts +│ ├── all-versions.sh # Updates all component versions +│ └── version-in-file.sh # Updates versions in specific files +├── git/ +│ └── pre-commit.sh # Basic pre-commit (only runs `npm run fix:format:staged`) +├── _md-rules/ # Markdown validation rules +│ ├── trim-code-blank-lines.js +│ ├── unindent-code-blocks.js +│ └── validate-links.js +├── check-build-log.sh # Build log validation +├── check-i18n.sh # Localization drift detection +├── check-registry-urls # Registry URL validation +├── registry-scanner/ # Registry scanning tools +├── stats/ # Documentation statistics +└── content-modules/ # Content module processing +``` + +**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 +- ❌ No mdatagen integration +- ❌ No automated freshness tracking +- ❌ No husky setup for comprehensive pre-commit hooks + +If these challenges are not addressed: + +- Documentation will continue to drift from actual software behavior. +- Maintainers will spend excessive time on manual updates and build fixes. +- Users will encounter inaccurate or outdated information. +- Contributor experience will suffer from slow feedback loops. + +### Goals, objectives, and requirements + +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. + +**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. +- 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. + +### 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. + +### 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. +- **External link validation**: Regular checks for broken external links. +- **API/SDK version comparisons**: Alerts when documented versions fall behind + latest releases. + +### Contributor tooling + +- **Pre-commit hooks**: Using [husky](https://github.com/typicode/husky) for: + - Markdown linting. + - Spell checking. + - Format validation. + - Link checking (local). +- **Local validation scripts**: Easy-to-run scripts for common validation tasks. +- **Documentation**: Guide for setting up and using local tooling. + +### 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. + +## Timeline + +- **Month 1**: Audit current automation, document requirements. +- **Month 2**: Implement pre-commit hooks and local tooling. +- **Month 3**: Fix version update automation for patch releases. +- **Month 4**: Implement mdatagen integration for Collector metrics. +- **Month 5**: Build content freshness tracking system. +- **Month 6**: Testing, documentation, and rollout. + +## Labels + +- `docs:CI/infra` +- `sig:comms` +- `sig:collector` + +## 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. + +## 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. + +- **Slack channel**: `#otel-comms` +- **Meeting notes**: To be linked upon project start. diff --git a/projects/docs-search-discovery.md b/projects/docs-search-discovery.md new file mode 100644 index 000000000000..700ae05e68e3 --- /dev/null +++ b/projects/docs-search-discovery.md @@ -0,0 +1,146 @@ +# Documentation Search and Discovery + +## Background and description + +As the OpenTelemetry documentation has grown to cover multiple languages, +components, and concepts, finding relevant information has become increasingly +challenging. Users often struggle to locate specific content, particularly in +large reference sections like the Semantic Conventions attribute registry. + +This project aims to improve the findability and discoverability of +documentation content through enhanced search functionality and better +navigation patterns. + +### Current challenges + +The current documentation has several discoverability issues: + +- **Semantic conventions attribute registry lacks search**: The attribute + registry is extensive, spanning many namespaces, making it difficult for users + to find specific attributes without knowing which namespace to look in. +- **General search limitations**: While the site has search functionality, it + doesn't always surface the most relevant results, particularly for technical + queries. +- **Navigation challenges**: Users may not know where to look for specific types + of content, leading to frustration and potential abandonment. +- **Cross-referencing gaps**: Related content is not always well-linked, missing + opportunities to guide users to relevant information. + +**Existing search functionality verified in repository:** + +The Registry already has search implemented (`assets/js/registrySearch.js`): + +```javascript +// Uses MiniSearch library for fuzzy search +const miniSearchOptions = { + fields: [ + 'title', + 'description', + '_key', + 'tags', + 'package.name', + 'flags', + 'license', + 'language', + 'registryType', + ], + searchOptions: { + prefix: true, + boost: { title: 4, tags: 3, description: 2 }, + fuzzy: 0.2, + }, +}; +``` + +**Features:** + +- ✅ Full-text search across registry entries +- ✅ Auto-suggest functionality +- ✅ Language filtering dropdown +- ✅ Component type filtering +- ✅ Flags filtering (first-party, third-party, etc.) +- ✅ URL parameter support for shareable searches + +**What's missing:** + +- ❌ Search for semantic conventions attributes (different from registry) +- ❌ Cross-site search with result categorization +- ❌ "Related content" suggestions on pages +- ❌ Search analytics to identify documentation gaps + +If these challenges are not addressed: + +- Users will continue to struggle finding the information they need. +- Support burden increases as users ask questions that could be answered by + existing documentation. +- Adoption may suffer as potential users give up searching for answers. + +### Goals, objectives, and requirements + +The goal of this project is to: + +1. **Add search to semantic conventions registry**: Implement search + functionality specifically for the attribute registry. +2. **Improve overall site search**: Enhance search relevance and categorization. +3. **Better cross-referencing**: Improve links between related content. +4. **Enhanced navigation**: Add navigation aids like "related pages" sections. + +**Motivations for starting now**: + +- The semantic conventions documentation continues to grow with new namespaces. +- User feedback consistently highlights difficulty finding specific attributes. +- Better discoverability directly improves the user experience and adoption. + +## Deliverables + +### Semantic conventions search + +- **Attribute registry search**: Search functionality that works across all + semconv namespaces. +- **Filtering options**: Filter by namespace, stability level, or attribute + type. +- **Quick lookup**: Fast lookup for known attribute names. + +### Site search improvements + +- **Search result categorization**: Group results by section (Languages, + Collector, Concepts, etc.). +- **Search result snippets**: Better context in search results. +- **Search analytics**: Track common searches to identify documentation gaps. + +### Navigation enhancements + +- **Related content sections**: "See also" or "Related pages" on relevant pages. +- **Improved breadcrumbs**: Clear location indicators throughout the site. +- **Quick navigation**: Jump-to-section functionality for long pages. + +## Timeline + +- **Month 1**: Research and design search implementation options. +- **Month 2-3**: Implement semantic conventions attribute registry search. +- **Month 4**: Improve overall site search. +- **Month 5**: Add related content sections and navigation improvements. +- **Month 6**: Testing, refinement, and launch. + +## Labels + +- `docs:CI/infra` +- `sig:semconv` +- `sig:comms` + +## Related issues + +- [#6569 - Support search over semconv attributes registry](https://github.com/open-telemetry/opentelemetry.io/issues/6569) + (open) - Primary issue for registry search. + +## 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 Semconv. + +- **Slack channel**: `#otel-comms` +- **Meeting notes**: To be linked upon project start. diff --git a/projects/getting-started-enhancement.md b/projects/getting-started-enhancement.md new file mode 100644 index 000000000000..07b1eb1a7d0c --- /dev/null +++ b/projects/getting-started-enhancement.md @@ -0,0 +1,169 @@ +# Getting Started Experience Enhancement + +## Background and description + +The getting started experience is critical for OpenTelemetry adoption. New users +need clear pathways to understand what OpenTelemetry offers and how to begin +using it based on their role and goals. The current getting started +documentation addresses developers and operators but could be expanded to serve +additional user personas with more tailored guidance. + +This project aims to enhance the getting started experience by creating +persona-based guides, progressive learning paths, and migration resources for +users coming from other observability tools. + +**Note**: This project complements the existing +[New Getting Started Documentation and Reference Application](new-getting-started-docs-and-reference-application.md) +project, which focuses on creating a reference implementation. This project +focuses on the documentation structure and content around getting started. + +### Current challenges + +The current getting started experience has several gaps: + +- **Limited persona coverage**: Only "Dev" and "Ops" roles are explicitly + addressed, missing SREs, Platform Engineers, Security Engineers, and technical + decision-makers. +- **Role-specific depth**: The existing role-based guides could go deeper into + specific concerns for each persona. +- **No progressive structure**: There's no clear progression from "first steps" + to "production-ready" implementation. +- **Missing migration content**: Users coming from other observability solutions + (Prometheus, Jaeger, proprietary tools) lack guidance on migration. +- **Evaluation guidance**: Technical decision-makers lack content to help them + evaluate OpenTelemetry for their organization. + +**Current structure verified in repository +(`content/en/docs/getting-started/`):** + +``` +getting-started/ +├── _index.md # Landing page +├── dev.md # Developer guide +├── ops.md # Operator guide +└── reference-application-specification.md # Reference app spec (related project) +``` + +**Content analysis:** + +- `_index.md`: Landing page with role-based navigation (Dev/Ops only) +- `dev.md`: Developer-focused guide with language quickstarts +- `ops.md`: Operator-focused guide with Collector emphasis +- `reference-application-specification.md`: Specification for the reference + application (separate project) + +**What's missing:** + +- ❌ SRE guide (reliability, SLOs, alerting) +- ❌ Platform Engineer guide (infrastructure, multi-tenancy) +- ❌ Security Engineer guide (audit logging, compliance) +- ❌ Decision-maker guide (evaluation, TCO, adoption roadmap) +- ❌ Migration guides from other tools +- ❌ Progressive learning path (quick start → basic → production → advanced) + +If these challenges are not addressed: + +- Potential adopters may not find the onboarding content that addresses their + specific needs. +- Users may struggle to progress from initial experimentation to production + deployment. +- Organizations considering OpenTelemetry lack the evaluation resources they + need to make informed decisions. + +### Goals, objectives, and requirements + +The goal of this project is to: + +1. **Expand persona coverage**: Create content for SREs, Platform Engineers, + Security Engineers, and decision-makers. +2. **Deepen existing guides**: Enhance Dev and Ops guides with more detailed + content. +3. **Create progressive paths**: Clear learning paths from beginner to advanced. +4. **Add migration guides**: Help users transition from other observability + tools. +5. **Support evaluation**: Content to help organizations evaluate OpenTelemetry. + +**Motivations for starting now**: + +- OpenTelemetry is being evaluated by many organizations as they modernize their + observability practices. +- Competition from proprietary solutions requires clear articulation of + OpenTelemetry's benefits. +- User feedback indicates that role-specific content helps with adoption. + +## Deliverables + +### Expanded persona guides + +- **SRE Guide**: Focus on reliability, SLOs, alerting integration, and incident + response. +- **Platform Engineer Guide**: Focus on platform integration, multi-tenancy, and + infrastructure observability. +- **Security Engineer Guide**: Focus on security observability, audit logging, + and compliance. +- **Decision-Maker Guide**: Evaluation criteria, TCO analysis, and adoption + roadmaps. + +### Enhanced existing guides + +- **Developer Guide Enhancement**: More depth on instrumentation patterns, + debugging, and testing. +- **Operator Guide Enhancement**: More depth on deployment patterns, scaling, + and monitoring. + +### Progressive learning paths + +- **Quick Start**: 5-minute introduction to see OpenTelemetry in action. +- **Basic Implementation**: First real instrumentation in your application. +- **Production Ready**: Best practices for production deployment. +- **Advanced Topics**: Custom instrumentation, performance optimization, complex + architectures. + +### Migration guides + +- **From Prometheus**: Migrating metrics collection to OpenTelemetry. +- **From Jaeger/Zipkin**: Migrating tracing to OpenTelemetry. +- **From proprietary tools**: General guidance for migrating from + vendor-specific solutions. +- **Gradual migration patterns**: How to adopt OpenTelemetry incrementally. + +### Evaluation resources + +- **OpenTelemetry vs. alternatives**: Objective comparison content. +- **Adoption checklist**: What to consider when adopting OpenTelemetry. +- **Success stories**: Case studies from organizations using OpenTelemetry. + +## Timeline + +- **Month 1**: User research and persona definition. +- **Month 2-3**: Create SRE and Platform Engineer guides. +- **Month 4**: Create Security Engineer and Decision-Maker guides. +- **Month 5**: Develop progressive learning paths. +- **Month 6-7**: Create migration guides. +- **Month 8**: Develop evaluation resources. +- **Month 9**: User testing, refinement, and launch. + +## Labels + +- `docs:getting-started` +- `sig:comms` +- `help wanted` + +## Related issues + +No directly related open issues found. This builds upon the existing getting +started structure. + +Related project: +[New Getting Started Documentation and Reference Application](new-getting-started-docs-and-reference-application.md) + +## Project Board + +To be created upon project approval. + +## SIG Meetings and Other Info + +This project will be coordinated through SIG Communications meetings. + +- **Slack channel**: `#otel-comms` +- **Meeting notes**: To be linked upon project start. diff --git a/projects/introductory-conceptual-docs.md b/projects/introductory-conceptual-docs.md new file mode 100644 index 000000000000..10e852a1917e --- /dev/null +++ b/projects/introductory-conceptual-docs.md @@ -0,0 +1,230 @@ +# Introductory Materials and Conceptual Documentation + +## Description + +OpenTelemetry's conceptual documentation serves as the foundation for +understanding the project. However, the current documentation assumes +significant prior knowledge of observability concepts and jumps quickly into +technical details without providing adequate context for newcomers. + +This project aims to create comprehensive, beginner-friendly conceptual content +that helps users understand not just _what_ OpenTelemetry is, but _why_ it +matters and _how_ it solves real-world problems. + +### Current challenges + +The current conceptual documentation has several gaps that create barriers for +new users: + +- **Assumes too much prior knowledge**: The documentation jumps directly into + technical concepts like spans, traces, and exporters without explaining why + these concepts exist or what problems they solve. +- **No clear problem-solution narrative**: Users don't get a clear understanding + of "what problem does OpenTelemetry solve?" before being presented with + technical details. +- **Missing visual explanations**: Complex concepts like distributed tracing, + context propagation, and the Collector pipeline lack visual diagrams that + would aid comprehension. +- **No progressive learning structure**: There's no clear path from beginner to + intermediate to advanced understanding. Users are expected to absorb all + concepts at once. +- **Lack of real-world examples**: The documentation doesn't show how + OpenTelemetry concepts apply to real-world scenarios that users can relate to. +- **Disconnected from implementation**: Concepts are explained in isolation + without clear connections to how users would actually implement them. +- **Missing motivation**: Each concept lacks a "why should I care?" section that + explains its practical benefits. +- **Underutilized glossary**: The glossary exists but isn't integrated into the + learning flow or referenced contextually. +- **Missing key concepts**: Documentation for Entities, Events, Profiles, and + Attributes is missing from the concepts section. +- **Fragmented content**: Concept documentation (e.g., metrics types) is split + across concepts, specs, and other sections rather than being consolidated. + +**Current state assessment** (verified against repository): + +| Page | Status | Actual Content | Issues | +| --------------------------- | ------------------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| `what-is-opentelemetry.md` | **Better than expected** | 152 lines with video, "Why OpenTelemetry?" section, components list | Could use more visual diagrams, better "what problem does this solve" framing | +| `observability-primer.md` | Good foundation | Explains observability concept | Jumps quickly to technical details | +| `concepts/_index.md` | **Minimal** | Only 2 meaningful lines: "This section covers data sources and key components" | Needs proper introduction and learning path | +| `signals/_index.md` | Reasonable | 35 lines explaining signals concept with links | Good structure but could be more beginner-friendly | +| `instrumentation/_index.md` | Good structure | Proper hierarchy with code-based, zero-code, libraries subsections | Technical but well-organized | +| `context-propagation/` | **Good** | Recently updated with SVG diagram | Can serve as model for other concept pages | +| `sampling/` | **Good** | Dedicated page with diagrams (traces-venn-diagram.svg, tail-sampling-process.svg) | Well-structured with visual aids | +| `resources/` | Good | Has screenshot example | Reasonable coverage | + +**Verified missing concepts:** + +- **Entities** - No dedicated page in concepts/ +- **Events** - Only mentioned in signals/\_index.md as "under development" +- **Profiles** - Only mentioned as "being worked on by the Profiling Working + Group" +- **Attributes** - No dedicated page (mentioned throughout but no comprehensive + guide) + +If these challenges are not addressed, new users will continue to struggle with +understanding OpenTelemetry, leading to: + +- Higher abandonment rates during onboarding. +- Increased support burden on community channels. +- Slower adoption of OpenTelemetry. +- Users making suboptimal implementation decisions due to incomplete + understanding. + +### Goals, objectives, and requirements + +The goal of this project is to create a comprehensive, beginner-friendly +conceptual documentation experience that: + +1. **Explains the "why" before the "what"**: Each concept should start with the + problem it solves. +2. **Provides progressive learning**: Clear pathways from beginner to advanced + understanding. +3. **Uses visual explanations**: Diagrams, flowcharts, and illustrations for all + major concepts. +4. **Includes real-world examples**: Practical scenarios that demonstrate + concepts in action. +5. **Connects concepts to implementation**: Bridge content that shows how + concepts translate to code. +6. **Integrates the glossary**: Contextual definitions and cross-references + throughout. +7. **Supports multiple learning styles**: Text, visuals, videos, and interactive + elements. +8. **Consolidates concept documentation**: Ensure complete concept coverage + without requiring users to navigate to specs. + +**Motivations for starting now**: + +- User feedback consistently indicates that conceptual documentation is a + barrier to adoption. +- As OpenTelemetry approaches CNCF graduation, comprehensive documentation is + essential. +- New signals (profiles, events) are being added, requiring a scalable + conceptual framework. +- Recent improvements to context propagation documentation (PR #8468) show a + path forward. + +## Deliverables + +### Documentation restructure + +- Expanded `concepts/_index.md` with a proper introduction and learning path. +- Rewritten "What is OpenTelemetry?" page with deeper content. +- Enhanced observability primer with more context and examples. +- Consolidate concept documentation to avoid fragmentation across specs and + concepts. + +### New content - Missing concepts + +Address the missing concepts identified in +[#7280](https://github.com/open-telemetry/opentelemetry.io/issues/7280): + +- **Entities** - Documentation explaining the concept of entities in + OpenTelemetry. +- **Events** - Documentation explaining the concept of events. +- **Profiles** - Documentation explaining the new profiles signal. +- **Attributes** - Comprehensive documentation on attributes usage and best + practices. + +### New content - Introductory materials + +- **"Why Observability?"** - A new page explaining the business and technical + value of observability. +- **"OpenTelemetry for Beginners"** - A comprehensive introduction for users + with no prior observability experience. +- **Signal-specific guides**: + - "Understanding Traces" with visual trace diagrams. + - "Understanding Metrics" with practical examples and metric types (addressing + [#7281](https://github.com/open-telemetry/opentelemetry.io/issues/7281)). + - "Understanding Logs" with correlation examples. +- **"How OpenTelemetry Works"** - An architectural overview with diagrams. +- **Use case examples**: + - Debugging a slow API endpoint. + - Investigating a production incident. + - Monitoring application performance. + - Tracking user journeys across services. + +### Visual content + +- Architectural diagrams for OpenTelemetry components. +- Flowcharts for data flow (instrumentation → collection → export). +- Visual explanations of context propagation (building on PR #8468). +- Comparison diagrams (before/after OpenTelemetry). + +### Learning aids + +- Progressive learning path with suggested reading order. +- Concept checklists ("Do you understand X? If not, read Y"). +- Glossary integration with hover definitions or contextual links. +- Video content recommendations or embedded videos. + +### Terminology improvements + +Address terminology confusion identified in +[#3228](https://github.com/open-telemetry/opentelemetry.io/issues/3228): + +- Clarify instrumentation terminology (automatic, assisted, zero-code, + code-based). +- Ensure consistent terminology usage across all conceptual documentation. + +## Timeline + +- **Month 1**: Audit existing content, define learning paths, and create content + outline. +- **Month 2**: Write "Why Observability?" and "OpenTelemetry for Beginners" + pages. +- **Month 3**: Create signal-specific guides (Traces, Metrics, Logs) and missing + concepts (Entities, Events, Profiles, Attributes). +- **Month 4**: Develop visual content and diagrams. +- **Month 5**: Create use case examples and integrate glossary. +- **Month 6**: User testing, refinement, and launch. + +## Labels + +- `docs:concepts` +- `sig:comms` +- `sig:spec` +- `good first issue` (for some tasks) +- `help wanted` + +## Linked Issues and PRs + +### Open issues + +- [#7280 - Concepts are missing from the concept section](https://github.com/open-telemetry/opentelemetry.io/issues/7280) - + Documents need for Entities, Events, Profiles, and Attributes concept pages. +- [#7281 - Concept section needs to be able to provide complete concept](https://github.com/open-telemetry/opentelemetry.io/issues/7281) - + Concept documentation (like metrics types) should be consolidated, not split + across sections. +- [#3228 - Terminology Suggestion: Change "Manual Instrumentation" to "Code based Instrumentation"](https://github.com/open-telemetry/opentelemetry.io/issues/3228) - + Related to clarifying instrumentation terminology. + +### Merged PRs (reference implementations) + +- [#8468 - Update context propagation concept page](https://github.com/open-telemetry/opentelemetry.io/pull/8468) + (merged) - Major rework of context propagation documentation, can serve as a + model for other concept pages. +- [#7157 - Update Assisted and Automatic Instrumentation](https://github.com/open-telemetry/opentelemetry.io/pull/7157) + (blocked) - Renames "zero-code" terminology, introduces "assisted" concept. + +### Closed issues (reference) + +- [#1689 - Add a section in Components about "agents" & what to use instead of "agent"?](https://github.com/open-telemetry/opentelemetry.io/issues/1689) + (closed) - Related to clarifying terminology and concepts. + +## Project Board + +To be created upon project approval. + +## Discussion + +- **Slack channel**: `#otel-comms` + +## Meeting Times + +To be determined upon project approval. + +### Meeting Links + +To be added upon project start. diff --git a/projects/landing-page-redesign.md b/projects/landing-page-redesign.md new file mode 100644 index 000000000000..60b65879c20b --- /dev/null +++ b/projects/landing-page-redesign.md @@ -0,0 +1,332 @@ +# Landing Page Redesign + +## Background and description + +The OpenTelemetry website landing page serves as the first impression for +thousands of potential users, contributors, and adopters. As OpenTelemetry has +matured into a widely adopted observability standard, the homepage needs to +evolve to better communicate its value proposition and guide diverse user +personas to relevant content. + +This project aims to modernize the OpenTelemetry homepage at +[opentelemetry.io](https://opentelemetry.io) to better serve the needs of +developers, operators, SREs, platform engineers, and decision-makers evaluating +OpenTelemetry for their organizations. + +### Inspiration Analysis: Kubernetes and Prometheus + +To inform this redesign, we analyzed the landing pages of two highly successful +CNCF projects: **Kubernetes** (kubernetes.io) and **Prometheus** +(prometheus.io). Both excel at communicating complex technical concepts to +beginners while maintaining depth for advanced users. + +#### Kubernetes.io Design Patterns + +1. **Concise, Powerful Tagline**: "Production-Grade Container Orchestration" — + Just 4 words that communicate both quality ("Production-Grade") and purpose + ("Container Orchestration"). No jargon, immediately understandable. + +2. **"Why Kubernetes?" Section**: Six clear feature cards that answer the + beginner's first question. Each card has: + - A descriptive title (e.g., "Automated rollouts and rollbacks") + - A 1-2 sentence explanation in plain English + - No assumed prior knowledge + +3. **Feature Cards with Clear Benefits**: + - **Service discovery and load balancing**: Kubernetes can expose a container + using the DNS name or using their own IP address. + - **Storage orchestration**: Automatically mount the storage system of your + choice. + - **Self-healing**: Restarts containers that fail, replaces containers, kills + containers that don't respond to your user-defined health check. + - **Horizontal scaling**: Scale your application up and down with a simple + command, with a UI, or automatically based on CPU usage. + +4. **Case Studies Section**: Real company logos and stories showing Kubernetes + in production — builds trust and demonstrates maturity. + +5. **Community Events**: Prominent display of KubeCon and community events — + shows the project is alive and thriving. + +6. **Clean Navigation**: Documentation, Blog, Training, Community — simple + hierarchy. + +#### Prometheus.io Design Patterns + +1. **Minimalist Hero**: Clean design with flame logo and tagline "From metrics + to insight" — elegant and memorable. + +2. **Technical Features Clearly Explained**: + - **Dimensional data model**: Time series identified by metric name and + key/value pairs + - **Powerful queries**: PromQL allows slicing and dicing of collected data + - **No reliance on distributed storage**: Single server nodes are autonomous + - **Pull model over HTTP**: Targets discovered via service discovery or + static config + - **Dashboarding and graphing**: Multiple modes of graphing and dashboarding + support + +3. **Architecture Diagram**: Visual representation of how Prometheus works — + helps beginners understand the system at a glance. + +4. **"Get Started" Prominence**: Clear pathway to first steps, not buried in + navigation. + +5. **Component Breakdown**: Clear explanation of each piece (Prometheus server, + Alertmanager, exporters, etc.). + +#### Key Lessons for OpenTelemetry + +| Aspect | Current OpenTelemetry | Kubernetes/Prometheus Best Practice | +| ------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| **Tagline** | "High-quality, ubiquitous, and portable telemetry to enable effective observability" (15 words, abstract) | 4-6 words, concrete benefit | +| **First Question** | Not answered | "Why X?" or "What is X?" section | +| **Features** | Listed as technical concepts | Explained as user benefits | +| **Visuals** | Logo only | Architecture diagrams, icons | +| **Social Proof** | CNCF badge only | Case studies, adopter logos | +| **Getting Started** | "Dev" and "Ops" links | Clear "Get Started" pathway | + +### Repository Verification + +**Current landing page verified in repository (`content/en/_index.md`):** + +```markdown +# Current structure (101 lines) + +{{< blocks/cover >}} + +- Logo: OpenTelemetry horizontal color SVG +- Tagline: "{{% param description %}}" (15 words) +- Primary CTAs: "Learn more" | "Try the demo" +- Role buttons: Dev | Ops {{< /blocks/cover >}} + +{{< blocks/lead >}} + +- Text description of OpenTelemetry +- Note about general availability {{< /blocks/lead >}} + +{{< blocks/section type="row" >}} + +- Feature 1: "Traces, Metrics, Logs" with fas fa-chart-line icon +- Feature 2: "Drop-in Instrumentation & Integrations" with fas fa-magic icon +- Feature 3: "Open Source, Vendor Neutral" with fab fa-github icon + {{< /blocks/section >}} + +{{< blocks/section type="cncf" >}} + +- CNCF incubating project badge {{< /blocks/section >}} +``` + +**Assets available:** + +- `assets/icons/logo.svg` - Main logo +- `assets/icons/logo-pride.svg` - Pride variant +- `static/img/logos/` - Various logo formats +- `iconography/` - 54 icons at 32x32 and 53 at 512x512 + +### Current challenges + +The current landing page has several limitations that affect user experience and +adoption: + +- **Wordy, abstract tagline**: "High-quality, ubiquitous, and portable telemetry + to enable effective observability" uses jargon and doesn't answer "what does + this do for me?" Compare to Kubernetes' "Production-Grade Container + Orchestration" or Prometheus' "From metrics to insight." + +- **Missing "Why OpenTelemetry?" section**: Beginners land on the page and + immediately see technical terms (traces, metrics, logs) without understanding + the problem being solved. Kubernetes explains benefits before technical + details. + +- **Limited persona targeting**: The homepage only addresses "Dev" and "Ops" + roles, missing other important personas such as SREs, Platform Engineers, + Security Engineers, and technical decision-makers evaluating OpenTelemetry. + +- **No architecture visualization**: Unlike Prometheus' clear architecture + diagram, OpenTelemetry's complex ecosystem (SDKs, Collector, exporters, + backends) isn't visualized. Beginners can't form a mental model. + +- **Missing social proof**: The page lacks adoption metrics, testimonials, case + studies, or evidence of widespread industry adoption. Kubernetes prominently + displays case studies from real companies. + +- **No ecosystem showcase**: Despite having 90+ vendor integrations and + thousands of libraries in the registry, the homepage doesn't effectively + showcase the size and breadth of the ecosystem. + +- **Basic design**: The current design uses standard Docsy theme blocks with + minimal customization, resulting in a generic appearance that doesn't reflect + the project's maturity and importance. + +If these challenges are not addressed, potential users may not fully appreciate +OpenTelemetry's capabilities, leading to slower adoption and missed +opportunities for the project to demonstrate its value. + +### Goals, objectives, and requirements + +The goal of this project is to create a modern, engaging, and informative +landing page that follows the successful patterns established by Kubernetes and +Prometheus: + +1. **Craft a concise, memorable tagline**: Create a 4-6 word tagline that + communicates what OpenTelemetry does and its value. Examples to explore: + - "The Standard for Observability Data" + - "Universal Telemetry for Modern Applications" + - "Instrument Once, Observe Everywhere" + +2. **Add a "Why OpenTelemetry?" section**: Like Kubernetes, create 4-6 feature + cards that explain benefits in plain English: + - **Vendor-neutral instrumentation**: Instrument your code once, send data + anywhere + - **Unified telemetry**: Traces, metrics, and logs with correlated context + - **Drop-in instrumentation**: Auto-instrument popular frameworks with zero + code changes + - **Industry standard**: Backed by major cloud providers and observability + vendors + - **Production-ready**: Stable APIs used by thousands of organizations + worldwide + - **Open source**: 100% free, CNCF-hosted, community-driven + +3. **Create an architecture visualization**: A simple diagram showing: + - Your Application → OpenTelemetry SDK → Collector → Any Backend + - Make the complex simple, like Prometheus does + +4. **Showcase the ecosystem**: Display: + - Number of supported languages (11+) + - Number of Collector components (200+) + - Number of vendor integrations (90+) + - Adopter logos (scrolling or grid) + +5. **Add case studies or testimonials**: Feature 3-5 real-world success stories + from adopters. + +6. **Simplify the getting started pathway**: Instead of just "Dev" and "Ops", + consider: + - "Get Started in 5 Minutes" primary CTA + - Secondary paths for different languages/use cases + - Try the demo prominently featured + +7. **Maintain accessibility and localization**: Meet WCAG 2.1 AA standards, + ensure the redesign works for all language localizations. + +**Motivations for starting now**: + +- OpenTelemetry is approaching graduation status at the CNCF, making this an + ideal time to refresh the public-facing homepage. +- User research and feedback indicate that newcomers struggle to understand what + OpenTelemetry offers. +- Competing projects have more modern and engaging websites that may attract + users who would benefit from OpenTelemetry. + +## Deliverables + +### Research and Planning + +- **Competitive analysis report**: Detailed analysis of Kubernetes, Prometheus, + and other successful project landing pages +- **User research report**: Analysis of user personas, their needs, and journey + mapping for the homepage +- **Proposed tagline options**: 3-5 tagline candidates with testing plan + +### Design + +- **Information architecture**: Revised structure for homepage content and + navigation +- **Wireframes**: Low-fidelity layouts showing new section structure +- **Design mockups**: High-fidelity mockups for desktop and mobile views +- **Prototype**: Interactive prototype for user testing + +### Content + +- **"Why OpenTelemetry?" copy**: 4-6 benefit cards with clear, jargon-free + explanations +- **Architecture diagram**: Simple visual showing OTel data flow +- **Ecosystem statistics**: Accurate counts of languages, components, + integrations +- **Case study summaries**: 3-5 adopter success stories (may require outreach) + +### Implementation + +- **Landing page implementation**: Full implementation of the redesigned + homepage +- **Component library updates**: Any new UI components needed +- **Localization**: Updates to all supported languages +- **Documentation**: Guidelines for maintaining and updating the homepage + +### Specific Features + +Inspired by Kubernetes and Prometheus patterns: + +| Feature | Inspiration | Priority | +| ------------------------------ | ------------------------------ | -------- | +| New concise tagline | Both | P0 | +| "Why OpenTelemetry?" cards | Kubernetes "Why Kubernetes?" | P0 | +| Architecture diagram | Prometheus architecture visual | P0 | +| Adopter logos section | Kubernetes case studies | P1 | +| Ecosystem statistics | Both | P1 | +| "Get Started in 5 Minutes" CTA | Both | P1 | +| Interactive demo link | OpenTelemetry demo | P1 | +| Community events section | Kubernetes events | P2 | +| Mobile-responsive design | Both | P0 | +| Accessibility improvements | Standard | P1 | + +## Timeline + +- **Month 1**: User research, competitive analysis, and information architecture + - Deliverables: Research report, tagline options, wireframes +- **Month 2**: Design exploration, mockups, and community feedback + - Deliverables: High-fidelity mockups, prototype +- **Month 3**: Content creation and user testing + - Deliverables: Copy for all sections, architecture diagram, case studies +- **Month 4**: Implementation and refinement + - Deliverables: Working implementation in staging +- **Month 5**: Accessibility audit, localization support, and final testing + - Deliverables: Accessibility report, localized content +- **Month 6**: Launch and post-launch monitoring + - Deliverables: Production launch, analytics setup + +## Labels + +- `docs:design/style` +- `sig:comms` +- `p1-high` + +## Related issues + +No directly related issues found. This would be a new initiative, inspired by +successful patterns from peer CNCF projects. + +## Project Board + +To be created upon project approval. + +## SIG Meetings and Other Info + +This project will be coordinated through SIG Communications meetings. Additional +design review sessions may be scheduled as needed. + +- **Slack channel**: `#otel-comms` +- **Meeting notes**: To be linked upon project start. + +## Appendix: Current vs. Proposed Structure + +### Current Landing Page Structure + +1. Hero: Logo + wordy tagline + "Learn more" / "Try the demo" +2. Role buttons: Dev / Ops +3. Lead section: Text description +4. Feature cards: Traces, Metrics, Logs / Drop-in Instrumentation / Open Source +5. CNCF badge + +### Proposed Landing Page Structure (Inspired by K8s/Prometheus) + +1. **Hero**: Logo + concise tagline (4-6 words) + "Get Started in 5 Minutes" CTA +2. **"What is OpenTelemetry?"**: 1-2 sentence plain-English explanation +3. **Architecture Diagram**: Visual showing SDK → Collector → Backend flow +4. **"Why OpenTelemetry?"**: 4-6 benefit cards (like Kubernetes) +5. **Ecosystem Showcase**: Statistics + vendor/adopter logos +6. **Getting Started Paths**: Language icons with quick links +7. **Case Studies/Testimonials**: Real-world success stories +8. **Community**: Events, Slack, contributing +9. **CNCF Badge**: Graduation status (when achieved) diff --git a/projects/language-sdk-docs-consistency.md b/projects/language-sdk-docs-consistency.md new file mode 100644 index 000000000000..6fcb8a06ab9d --- /dev/null +++ b/projects/language-sdk-docs-consistency.md @@ -0,0 +1,191 @@ +# Language SDK Documentation Consistency + +## Background and description + +OpenTelemetry provides SDKs for 13+ programming languages, each with its own +documentation on [opentelemetry.io](https://opentelemetry.io/docs/languages/). +While standardization efforts have improved consistency, significant gaps and +inconsistencies remain across language SDK documentation. + +This project aims to standardize and complete language SDK documentation across +all supported languages, ensuring users have a consistent experience regardless +of which language they're using. + +### Current challenges + +The current language SDK documentation has several issues: + +- **Inconsistent page structure**: Different languages have different + documentation structures. For example, Go has a dedicated sampling page while + .NET doesn't. Ruby is missing resource documentation that other languages + have. +- **Missing critical documentation**: + - Sampling documentation is missing for .NET, Python, and partially for Java. + - Testing instrumentation guides are missing for Go and most other languages. + - Context propagation documentation varies significantly in depth. + - Resource management documentation is incomplete for several languages. +- **Outdated content**: Some documentation is out of sync with the actual SDK + capabilities. For example, the Java agent instrumentation list doesn't match + the current `supported-libraries.md` in the repository. +- **Varying code example quality**: Some languages have comprehensive, tested + code examples while others have minimal or untested snippets. +- **No feature parity documentation**: Users cannot easily determine which + features are available in which languages or at what stability level. + +**Current state assessment** (verified against repository): + +| Language | Sampling | Testing | Context Prop | Resources | Config | Overall | +| ---------- | ------------------------------------------------- | ----------------------- | -------------------- | ---------- | ---------- | ---------- | +| Go | ✅ Dedicated page | ❌ Missing | ❌ No dedicated page | ✅ Yes | ⚠️ Partial | Good | +| .NET | ✅ Advanced (tail-based, stratified, links-based) | ⚠️ Partial | ⚠️ Partial | ✅ Yes | ✅ Yes | Good | +| Java | ✅ In sdk.md (comprehensive table) | ❌ Missing | ⚠️ Partial | ⚠️ Partial | ✅ Yes | Good | +| Python | ❌ Missing | ❌ Missing | ✅ Yes | ❌ Missing | ⚠️ Partial | Needs work | +| JavaScript | ✅ Yes | ❌ Missing | ✅ Yes | ✅ Yes | ⚠️ Partial | Good | +| Ruby | ✅ Dedicated page | ❌ Missing | ⚠️ In other docs | ❌ Missing | ❌ Missing | Needs work | +| PHP | ⚠️ Partial | ❌ Missing | ✅ Yes | ✅ Yes | ⚠️ Partial | Okay | +| Erlang | ✅ Yes | ✅ Yes (only language!) | ✅ Yes | ✅ Yes | ⚠️ Partial | Excellent | + +**Key findings from repository analysis:** + +1. **.NET has excellent sampling docs**: Contrary to initial assessment, .NET + has advanced sampling guides including: + - `traces/tail-based-sampling.md` - Comprehensive hybrid sampling approach + - `traces/stratified-sampling.md` - Per-route sampling strategies + - `traces/links-based-sampler.md` - Links-based sampling implementation + +2. **Erlang is the gold standard for testing**: The only language with a + dedicated `testing.md` that provides a complete testing approach with code + examples. + +3. **Java sampling is well-documented**: While not in a dedicated page, `sdk.md` + includes a comprehensive sampler comparison table with 7+ sampler + implementations. + +4. **Python and Ruby need the most work**: Both lack sampling and resources + documentation. + +5. **Go lacks propagation page**: Despite other SDKs having dedicated + propagation docs, Go doesn't have one. + +If these challenges are not addressed: + +- Users will have inconsistent experiences across languages, leading to + confusion and frustration. +- Teams using multiple languages will struggle to apply learnings from one + language to another. +- Missing documentation leads to support burden and incorrect implementations. +- OpenTelemetry's reputation for completeness and maturity suffers. + +### Goals, objectives, and requirements + +The goal of this project is to ensure all language SDK documentation: + +1. **Follows a standardized structure**: All languages have the same + documentation sections. +2. **Is complete**: All critical topics (sampling, testing, context propagation, + resources, configuration) are documented for every language. +3. **Is accurate**: Documentation matches current SDK capabilities. +4. **Has quality code examples**: All examples are tested and follow best + practices. +5. **Shows feature parity**: Users can easily see which features are available + in which languages. + +**Motivations for starting now**: + +- Several language SDKs have recently reached stable status, making this an + ideal time to complete documentation. +- User feedback consistently highlights documentation gaps as a barrier to + adoption. +- The Java SDK documentation restructure provides a template for other + languages. + +## Deliverables + +### Standardization + +- **SDK documentation template**: A standardized template defining required + sections for all language SDK documentation. +- **Gap analysis report**: Comprehensive report identifying missing pages and + content per language. +- **Style guide updates**: Language SDK-specific guidance in the documentation + style guide. + +### Missing documentation + +Implementation of missing pages for each language: + +- **Sampling documentation**: For .NET, Python, Java (expand), Ruby (context), + PHP. +- **Testing instrumentation guides**: For Go, .NET, Java, Python, JavaScript, + Ruby, PHP. +- **Context propagation**: For .NET (expand), Java (expand), Ruby. +- **Resource management**: For Python, Ruby. +- **SDK configuration reference**: Standardized configuration documentation for + all languages. +- **Error handling and troubleshooting**: Per-language troubleshooting guides. + +### Quality improvements + +- **Code example review and updates**: Audit all code examples for accuracy and + best practices. +- **Code example testing**: Framework for testing documentation code examples. +- **SDK feature parity matrix**: Publicly visible matrix showing feature + availability across languages. + +### Automation + +- **Drift detection**: Automated checks to identify when languages fall behind + the standard structure. +- **Version tracking**: Track SDK versions documented vs. latest releases. + +## Timeline + +- **Month 1**: Create standardized template, complete gap analysis. +- **Month 2-3**: Address .NET documentation gaps (sampling, context + propagation). +- **Month 4-5**: Address Python documentation gaps (sampling, resources, + testing). +- **Month 6-7**: Address Java documentation gaps (sampling expansion, testing). +- **Month 8-9**: Address Ruby and PHP documentation gaps. +- **Month 10**: Create SDK feature parity matrix. +- **Month 11**: Implement drift detection automation. +- **Month 12**: Final review and launch. + +## Labels + +- `sig:dotnet` +- `sig:go` +- `sig:java` +- `sig:js` +- `sig:python` +- `sig:ruby` +- `sig:php` +- `sig:erlang` +- `sig:comms` +- `help wanted` + +## Related issues + +- [#7302 - .NET docs doesn't mention support for samplers](https://github.com/open-telemetry/opentelemetry.io/issues/7302) + (open) - Missing sampling documentation for .NET. +- [#6899 - Go language docs: Add documentation for how to test instrumentation](https://github.com/open-telemetry/opentelemetry.io/issues/6899) + (open) - Missing testing documentation for Go. +- [#1630 - Document how to test that you're instrumenting traces correctly](https://github.com/open-telemetry/opentelemetry.io/issues/1630) + (open) - Cross-language testing documentation. +- [#971 - Guidance around using OTel for tracing in language SDKs](https://github.com/open-telemetry/opentelemetry.io/issues/971) + (open) - SDK usage guidance. +- [#6110 - Please add Go examples of how to create LoggerProvider for unit tests](https://github.com/open-telemetry/opentelemetry.io/issues/6110) + (open) - Go testing examples. + +## Project Board + +To be created upon project approval. + +## SIG Meetings and Other Info + +This project will require coordination across multiple SIGs: + +- **Primary coordination**: SIG Communications +- **Language SIG engagement**: Regular check-ins with each language SIG. +- **Slack channel**: `#otel-comms` +- **Meeting notes**: To be linked upon project start. diff --git a/themes/docsy b/themes/docsy index bbf68d4caae5..39ee7cafc3ec 160000 --- a/themes/docsy +++ b/themes/docsy @@ -1 +1 @@ -Subproject commit bbf68d4caae52e8c9a89964c3d04b383ee678d44 +Subproject commit 39ee7cafc3ecd96c5d80af6b690688a289168da0