Skip to content

Commit a24a615

Browse files
authored
Style guide improvements (#1187)
1 parent f70abe2 commit a24a615

File tree

1 file changed

+23
-1
lines changed

1 file changed

+23
-1
lines changed

STYLE_GUIDE.md

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ Definition paragraphs start with `::` and add the matching italicized term to
9292
the [specification index](https://spec.graphql.org/draft/#index), making it easy
9393
to reference them.
9494

95-
## Tone of voice
95+
## Tone of Voice
9696

9797
The GraphQL specification is a reference document and should use neutral and
9898
descriptive tone of voice.
@@ -104,3 +104,25 @@ The present tense is usually clearer and shorter:
104104
✅ Present: The client then sends a request to the server.
105105

106106
❌ Future: The client will then send a request to the server.
107+
108+
**Write in the third person**
109+
110+
The specification should avoid the first person (“we,” “our”) and instead use
111+
the third person or passive constructions when necessary. For example:
112+
113+
✅ “The server validates the request against the schema.”
114+
115+
❌ “We validate the request against the schema.”
116+
117+
**Use RFC 2119 keywords**
118+
119+
The specification should use the normative keywords defined in
120+
[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) (**MUST**, **MUST NOT**,
121+
**SHOULD**, **SHOULD NOT**, **MAY**). However, in the context of a sentence
122+
these words should be lower-cased (e.g., “must,” “should,” “may”) in context of
123+
a sentence. This avoids unnecessary visual emphasis while preserving normative
124+
meaning.
125+
126+
✅ “A query must contain a single root operation type.”
127+
128+
❌ “A query MUST contain a single root operation type.”

0 commit comments

Comments
 (0)