diff --git a/pkg/front_end/lib/src/fasta/diagnostics.md b/pkg/front_end/lib/src/fasta/diagnostics.md
index d3711ec..1305e52 100644
--- a/pkg/front_end/lib/src/fasta/diagnostics.md
+++ b/pkg/front_end/lib/src/fasta/diagnostics.md
@@ -41,7 +41,9 @@
 
 ## Avoid Composing Messages Programmatically
 
-Composing messages programmatically can make it hard to translate them.
+Composing messages programmatically can make it hard to translate them. A tool that compose messages programmatically also makes it hard for its clients to distinguish the diagnostics.
+
+For example, [messages.yaml](../../../messages.yaml) includes an error code named `Unspecified`. This code is useful when prototyping a new diagnostic, but shouldn't otherwise be used.
 
 ## Keep Message Short
 
diff --git a/pkg/front_end/messages.yaml b/pkg/front_end/messages.yaml
index 989fd27..df83d386 100644
--- a/pkg/front_end/messages.yaml
+++ b/pkg/front_end/messages.yaml
@@ -64,6 +64,9 @@
 # `#lexeme` a token. The token's `lexeme` property is used.
 #
 # `#string`, `#string2`, `#string3`: strings (that aren't names).
+#    Note: as a rule of thumb, avoid using the `#string` keys. In particular,
+#    do not use them for composing error messages, see [diagnostics.md](
+#    lib/src/fasta/diagnostics.md#avoid-composing-messages-programmatically).
 #
 # `#type`, #type2`: Kernel types.
 #
@@ -864,6 +867,9 @@
   template: "Incomplete token."
   dart2jsCode: UNTERMINATED_TOKEN
 
+# Note: avoid using this template, it should only be used for debugging and
+# prototyping, see [diagnostics.md](
+# lib/src/fasta/diagnostics.md#avoid-composing-messages-programmatically).
 Unspecified:
   template: "#string"
   dart2jsCode: GENERIC