Attempt a write-up about t-shaped-signals. (#2232)

Co-authored-by: Steven E. Harris <seh@panix.com>
Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
Co-authored-by: Christophe Kamphaus <christophe.kamphaus@gmail.com>
Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>

.chloggen/wip-t-shaped-signals.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: docs
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Document the "T-Shaped" notion for defining semantic conventions.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [2232]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

docs/general/how-to-define-semantic-conventions.md

@@ -38,6 +38,10 @@ for new areas or make substantial changes to the existing ones.
 >
 > This section contains non-normative guidance.
 
+Please read [T-Shaped Signals](/docs/non-normative/how-to-write-conventions/t-shaped-signals.md)
+for guidance on how to approach creating Semantic Conventions through defining
+key use cases for conventions.
+
 #### Prototyping
 
 It is strongly recommended to prototype proposed conventions in one or more instrumentations and:

docs/non-normative/how-to-write-conventions/t-shaped-signals.md

@@ -0,0 +1,58 @@
+# T-shaped Signals
+
+Semantic Conventions approaches observability with a T-shaped mindset. This
+splits signals into two types of a "T" shape:
+
+```mermaid
+block-beta
+        columns 3
+          Broad["Broadly Applicable Signals"]:3
+        columns 3
+          space:1
+          Deep("Rich,\nDeep\nSignals")
+          space:1
+```
+
+This matches an 80-20 rule, where 80% of users (or use-cases) can leverage the
+broadly applicable signals and 20% of users (or use-cases) will dive deeply into
+a problem with deep signals.
+
+## Broadly Applicable Signals
+
+These are conventions meant to provide a baseline observability experience
+across a domain. An example includes HTTP semantic conventions that allow
+general-purpose dashboarding, alerting, and diagnostics for HTTP
+(micro-)services. These signals should provide "horizontal" coverage for
+observability.
+
+Examples include:
+
+- Golden Signals / RED metrics (Saturation, Rate, Error, Duration)
+- High Level Spans
+- Error logs, Crash reports
+- Request/Response logs
+
+## Rich, Deep Signals
+
+These are conventions meant to provide deep understanding of a specific
+system, library, module, application or service. These are used to diagnose
+issues specific to that system.
+
+Examples include:
+
+- Linux slab memory usage
+- Specific database signals, e.g MySQL index usage
+- Language-specific Garbage Collection metrics (JVM, Go, .NET, etc.)
+
+## Recommendations
+
+Defining semantic conventions is a balance between generating
+broadly applicable signals and ensuring rich observability for a specific
+technology. It is recommended to start with the *broad* use cases and signals
+for a particular domain first. After providing a baseline set of signals for
+that domain, then explore deeper integrations that may be vendor or
+implementation specific.
+
+For example, see [Database semantic conventions](/docs/database/README.md) where
+there is general guidance for spans about communicating with a database, and
+additionally there is database-specific guidance as an extension of the general.