[chore] Cleanup of docs #2426 (#2428)

thompson-tomo · joaopgrassi · web-flow · commit 33c54e59aa41 · 2025-09-08T14:14:46.000Z
Signed-off-by: James Thompson &lt;thompson.tomo@outlook.com&gt;
Co-authored-by: Joao Grassi &lt;5938087+joaopgrassi@users.noreply.github.com&gt;
diff --git a/docs/README.md b/docs/README.md
@@ -21,15 +21,14 @@ Semantic Conventions are defined for the following areas:
 
 * **[General](general/README.md): General Semantic Conventions**.
 * [CICD](cicd/README.md): Semantic Conventions for CICD systems.
-* [Code](code/README.md): Semantic Conventions for code.
 * [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries.
 * [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification.
 * [Database](database/README.md): Semantic Conventions for database operations.
 * [Exceptions](exceptions/README.md): Semantic Conventions for exceptions.
 * [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations.
 * [Feature Flags](feature-flags/README.md): Semantic Conventions for feature flag evaluations.
 * [Generative AI](gen-ai/README.md): Semantic Conventions for generative AI (LLM, etc.) operations.
-* [GraphQL](graphql/graphql-spans.md): Semantic Conventions for GraphQL implementations.
+* [GraphQL](graphql/README.md): Semantic Conventions for GraphQL implementations.
 * [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations.
 * [Messaging](messaging/README.md): Semantic Conventions for messaging operations and systems.
 * [Object Stores](object-stores/README.md): Semantic Conventions for object stores operations.
diff --git a/docs/app/README.md b/docs/app/README.md
@@ -0,0 +1,13 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: App
+--->
+
+# Semantic conventions for Apps
+
+**Status**: [Development][DocumentStatus]
+
+Semantic conventions for Apps are defined for the following signals:
+
+* [App Events](app-events.md)
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/app/app-events.md b/docs/app/app-events.md
@@ -1,8 +1,8 @@
 <!--- Hugo front matter used to generate the website version of this page:
-linkTitle: App
+linkTitle: Events
 --->
 
-# App
+# App Events
 
 **Status**: [Development][DocumentStatus]
 
diff --git a/docs/azure/README.md b/docs/azure/README.md
@@ -10,7 +10,7 @@ This document describes Azure Resource Logs, see [Azure Resource Log Top-level S
 
 Semantic conventions are defined for the following signals:
 
-* [Events](events.md)
+* [Events](azure-events.md)
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
 [AzureResourceSchema]: https://learn.microsoft.com/azure/azure-monitor/essentials/resource-logs-schema#top-level-common-schema
diff --git a/docs/azure/azure-events.md b/docs/azure/azure-events.md
diff --git a/docs/browser/README.md b/docs/browser/README.md
@@ -0,0 +1,15 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Browser
+--->
+
+# Semantic conventions for Browser
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for Browser.
+
+Semantic conventions are defined for the following signals:
+
+* [Events](browser-events.md)
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/browser/browser-events.md b/docs/browser/browser-events.md
diff --git a/docs/cli/README.md b/docs/cli/README.md
@@ -0,0 +1,13 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: CLI programs
+--->
+
+# Semantic conventions for CLI programs
+
+**Status**: [Development][DocumentStatus]
+
+Semantic conventions for CLI programs are defined for the following signals:
+
+* [CLI Spans](cli-spans.md)
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/cli/cli-spans.md b/docs/cli/cli-spans.md
@@ -1,5 +1,5 @@
 <!--- Hugo front matter used to generate the website version of this page:
-linkTitle: CLI programs
+linkTitle: Spans
 --->
 
 # Semantic conventions for CLI (command line interface) programs
diff --git a/docs/code/README.md b/docs/code/README.md
diff --git a/docs/dns/README.md b/docs/dns/README.md
@@ -0,0 +1,15 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: DNS
+--->
+
+# Semantic conventions for DNS
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for DNS.
+
+Semantic conventions are defined for the following signals:
+
+* [Metrics](dns-metrics.md)
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/dns/dns-metrics.md b/docs/dns/dns-metrics.md
@@ -1,5 +1,5 @@
 <!--- Hugo front matter used to generate the website version of this page:
-linkTitle: DNS
+linkTitle: Metrics
 --->
 
 # Semantic conventions for DNS queries
diff --git a/docs/general/attributes.md b/docs/general/attributes.md
@@ -420,7 +420,7 @@ Examples of where `thread.id` and `thread.name` can be extracted from:
 Often a span is closely tied to a certain unit of code that is logically responsible for handling
 the operation that the span describes (usually the method that starts the span).
 For an HTTP server span, this would be the function that handles the incoming request, for example.
-The [code attributes](https://opentelemetry.io/docs/specs/semconv/code/#attributes) allow to report this unit of code
+The [code attributes](https://opentelemetry.io/docs/specs/semconv/registry/attributes/code/) allow to report this unit of code
 and therefore to provide more context.
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/graphql/README.md b/docs/graphql/README.md
@@ -0,0 +1,15 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: GraphQL
+--->
+
+# Semantic conventions for GraphQL
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for GraphQL.
+
+Semantic conventions are defined for the following signals:
+
+* [Spans](graphql-spans.md)
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/mobile/README.md b/docs/mobile/README.md
@@ -10,6 +10,6 @@ This document defines semantic conventions for mobile platform spans, metrics an
 
 Semantic conventions for the mobile platform are defined for the following signals:
 
-* [Mobile Events](events.md) : Semantic Conventions for mobile events in *logs*.
+* [Mobile Events](mobile-events.md) : Semantic Conventions for mobile events in *logs*.
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/mobile/mobile-events.md b/docs/mobile/mobile-events.md
@@ -13,7 +13,7 @@ events on mobile platforms. All mobile events MUST use a namespace of
 <!-- toc -->
 
 - [Lifecycle instrumentation](#lifecycle-instrumentation)
-  - [Device app lifecycle event](#device-app-lifecycle-event)
+  - [Event: `device.app.lifecycle`](#event-deviceapplifecycle)
 
 <!-- tocstop -->
 
@@ -22,7 +22,7 @@ events on mobile platforms. All mobile events MUST use a namespace of
 This section defines how to apply semantic conventions when instrumenting
 application lifecycle.
 
-### Device app lifecycle event
+### Event: `device.app.lifecycle`
 
 <!-- semconv event.device.app.lifecycle -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
diff --git a/docs/otel/README.md b/docs/otel/README.md
@@ -0,0 +1,15 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: OpenTelemetry SDK
+--->
+
+# Semantic conventions for OpenTelemetry SDK
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for telemetry emitted by the OpenTelemetry SDK components.
+
+Semantic conventions are defined for the following signals:
+
+* [Metrics](sdk-metrics.md)
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/url/README.md b/docs/url/README.md
@@ -0,0 +1,21 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: URL
+--->
+
+# Semantic conventions for URL
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for url.
+
+* [Attributes](../registry/attributes/url.md)
+
+## Sensitive information
+
+Capturing URL and its components MAY impose security risk. User and password information, when they are provided in [User Information](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1) subcomponent, MUST NOT be recorded.
+
+Instrumentations that are aware of specific sensitive query string parameters MUST scrub their values before capturing `url.query` attribute. For example, native instrumentation of a client library that passes credentials or user location in URL, must scrub corresponding properties.
+
+_Note: Applications and telemetry consumers should scrub sensitive information from URL attributes on collected telemetry. In systems unable to identify sensitive information, certain attribute values may be redacted entirely._
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/url/url.md b/docs/url/url.md
