diff --git a/changelogs/internal/newsfragments/1582.clarification b/changelogs/internal/newsfragments/1582.clarification new file mode 100644 index 00000000..2f048a06 --- /dev/null +++ b/changelogs/internal/newsfragments/1582.clarification @@ -0,0 +1 @@ +Clarify usage of ABNF for grammar in the documentation style guide. diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 468b2675..e7b71408 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -185,3 +185,10 @@ The subheadings which are always deemed as client-affecting are: * Redactions When a new subheading is added, it must be referenced and ordered in this document. + +Describing grammar +~~~~~~~~~~~~~~~~~~ + +Use `RFC5234-style ABNF `_ when describing +the grammar for something in the spec, such as user IDs or server names. Use lowercase +and underscore-deliminated element names (`user_id`, not `UserID` or `user-id`).