Skip to content

docs: restructure observability documentation for clarity and neutrality#4249

Merged
jonpspri merged 1 commit intomainfrom
docs/observability-restructure-4245
Apr 16, 2026
Merged

docs: restructure observability documentation for clarity and neutrality#4249
jonpspri merged 1 commit intomainfrom
docs/observability-restructure-4245

Conversation

@vishu-bh
Copy link
Copy Markdown
Collaborator

Summary

Restructures the observability documentation to improve clarity, eliminate duplication, and use neutral language that describes capabilities rather than prescribing choices.

Changes

New Files

  • **** - Comprehensive Prometheus metrics guide (extracted from landing page)
  • **** - Span attributes reference (moved from repository root)

Renamed Files

  • → (clearer naming)
  • → (shorter, clearer)

Updated Files

  • **** - Rewritten landing page with neutral language and comparison matrix
  • **** - Updated navigation structure
  • Cross-references - Fixed all broken links in langfuse.md, phoenix.md, and architecture docs

Key Improvements

  1. Eliminated Duplication - Prometheus content extracted to dedicated file
  2. Neutral Language - Removed prescriptive terms like "Perfect for", "Ideal for", "Essential for"
  3. Factual Descriptions - Changed from "Use When" to "Characteristics" and "Common Use Cases"
  4. Better Organization - Clear separation between user guides (manage/) and technical docs (architecture/)
  5. Complete Cross-References - All documentation properly linked

Documentation Structure

docs/docs/
├── manage/
│   ├── observability.md (landing page)
│   └── observability/
│       ├── opentelemetry.md (external backends)
│       ├── internal.md (built-in tracing)
│       ├── prometheus.md (NEW - metrics)
│       ├── langfuse.md (LLM observability)
│       └── phoenix.md (AI/LLM observability)
└── architecture/
    ├── observability-otel.md (OTEL architecture)
    └── otel-span-attributes.md (NEW - span reference)

Testing

  • Documentation builds successfully with make: Nothing to be done for `build'.
  • All cross-references verified
  • Navigation structure updated
  • No broken links

Closes #4245

@vishu-bh vishu-bh mentioned this pull request Apr 16, 2026
@vishu-bh vishu-bh added documentation Improvements or additions to documentation observability Observability, logging, monitoring COULD P3: Nice-to-have features with minimal impact if left out; included if time permits labels Apr 16, 2026
@vishu-bh vishu-bh added this to the Release 1.0.0 milestone Apr 16, 2026
@vishu-bh vishu-bh force-pushed the docs/observability-restructure-4245 branch 4 times, most recently from 181969c to 147de31 Compare April 16, 2026 14:16
@ja8zyjits
Copy link
Copy Markdown
Member

Hi @vishu-bh
Thanks for a comprehensive documentation for Obeservability.
Cursory reading reveals this is really good.
Please fix the PR description.

Regards,
Jitesh

- Extract Prometheus metrics to dedicated guide (prometheus.md)
- Rename files for clarity:
  - observability/observability.md → opentelemetry.md
  - internal-observability.md → internal.md
- Move OTEL_SPAN_ATTRIBUTES.md to architecture/otel-span-attributes.md
- Rewrite landing page with neutral, descriptive language
- Remove prescriptive recommendations, use factual descriptions
- Update all cross-references and navigation
- Add comprehensive comparison matrix
- Add pragma comments for documentation example tokens

Closes #4245

Signed-off-by: Vishu Bheda <vishubheda@gmail.com>
Signed-off-by: Vishu Bhatnagar <vishu.bhatnagar@ibm.com>
@jonpspri jonpspri force-pushed the docs/observability-restructure-4245 branch from 147de31 to 34debd8 Compare April 16, 2026 19:58
@jonpspri jonpspri merged commit 27dfd8f into main Apr 16, 2026
16 checks passed
@jonpspri jonpspri deleted the docs/observability-restructure-4245 branch April 16, 2026 20:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

COULD P3: Nice-to-have features with minimal impact if left out; included if time permits documentation Improvements or additions to documentation observability Observability, logging, monitoring

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCS]:

3 participants