From 0a004c4709b3c44ee624da778b76a549ac6923da Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Mon, 26 Jan 2026 23:43:06 -0800 Subject: [PATCH] add clarity about usage --- informational/chat_cast.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/informational/chat_cast.md b/informational/chat_cast.md index d6b9df2..e1a0c29 100644 --- a/informational/chat_cast.md +++ b/informational/chat_cast.md @@ -16,7 +16,8 @@ The goal is to improve clarity and consistency when describing protocol roles, a ## Background When documenting applications and protocols, it is often beneficial to define a consistent set of characters representing common roles. -A shared cast allows authors to convey meaning and intent without repeatedly redefining actors and their properties. +A shared cast allows authors to convey meaning and intent quickly to readers. +Readers are not required to understand these meanings, however consistent usage can make comprehension faster to achieve. This approach is well established in cryptographic literature, where `Alice` and `Bob` are commonly used to describe participants in key exchange protocols. Within that context, Alice typically initiates the exchange and Bob responds. @@ -36,15 +37,24 @@ For these reasons, when documenting communication protocols that integrate multi ### Use of Alice and Bob `Alice` and `Bob` SHOULD be used when describing novel cryptographic constructions or key exchange mechanisms that are not embedded within higher-layer communication protocols. - -These names are widely understood by readers in cryptographic contexts, and introducing alternative names in such cases is likely to reduce clarity rather than improve it. +These names are widely understood in cryptographic contexts, and introducing alternatives would reduce clarity. Communication protocols may incorporate cryptographic components, but they are not themselves cryptographic key exchanges. -Descriptions of encodings, payload formats, transport behavior, or reliability mechanisms would be out of place in a cryptographic specification. - -When documenting processes that are primarily application-centric or protocol-level, the cast defined in this document SHOULD be used instead. +When documenting application-centric or protocol-level processes, the cast defined in this document SHOULD be used instead. This separation establishes clear contextual boundaries and prepares the reader to reason about different layers independently. +### Standalone Documents + +Knowledge of this cast MUST NOT be a requirement to understand a given document. +Documents MUST be fully standalone and understandable to first-time readers. + +### Consistency + +Use of the cast is optional. +Characters SHOULD only be used when their presence improves understanding. +Using characters in the wrong context can negatively impact comprehension by implying incorrect information. +It is always acceptable to use other identifiers. + ## Character List The following characters are defined for use throughout the documentation of chat protocols.