[doc only] Bug 1671621: Talk about write-only metric APIs (#1307)

docs/user/adding-new-metrics.md

@@ -197,6 +197,13 @@ The `metrics.yaml` file is used to generate code in the target language (e.g. Ko
 
 The [reference documentation for each metric type](metrics/index.html) goes into detail about using each metric type from your code.
 
+Note that all Glean metrics are write-only. Outside of unit tests, it is impossible to retrieve a value from the Glean SDK's database.
+While this may seem limiting, this is required to:
+- enforce the semantics of certain metric types (e.g. that Counters can only be incremented).
+- ensure the lifetime of the metric (when it is cleared or reset) is correctly handled.
+
+### Capitalization
+
 One thing to note is that we try to adhere to the coding conventions of each language wherever possible, to the metric name in the `metrics.yaml` (which is in `snake_case`) may be changed to some other case convention, such as `camelCase`, when used from code.
 
 {{#include ../tab_header.md}}

docs/user/testing-metrics.md

@@ -4,6 +4,7 @@ In order to support unit testing inside of client applications using the Glean S
 The intent is to make the Glean SDK easier to test 'out of the box' in any client application it may be used in.
 These functions expose a way to inspect and validate recorded metric values within the client application but are restricted to test code only through visibility annotations
 (`@VisibleForTesting(otherwise = VisibleForTesting.NONE)` for Kotlin, `internal` methods for Swift).
+(Outside of a testing context, Glean APIs are otherwise write-only so that it can enforce semantics and constraints about data).
 
 ## General test API method semantics