Skip to content

Commit e1056fc

Browse files
committed
Add tone of voice and definitions to the style guide
1 parent 7073e3a commit e1056fc

File tree

1 file changed

+21
-0
lines changed

1 file changed

+21
-0
lines changed

STYLE_GUIDE.md

+21
Original file line numberDiff line numberDiff line change
@@ -82,3 +82,24 @@ MyAlgorithm(argOne, argTwo):
8282
- Let {something} be {true}.
8383
- Return {something}.
8484
```
85+
86+
## Definitions
87+
88+
For important terms, use [Spec Markdown definition paragraphs](https://spec-md.com/#sec-Definition-Paragraph).
89+
90+
Definition paragraphs start with `::` and addsthe matching italicized term to the
91+
[specification index](https://spec.graphql.org/draft/#index), making it easy to
92+
reference them.
93+
94+
## Tone of voice
95+
96+
The GraphQL specification is a reference document and should use neutral and
97+
descriptive tone of voice.
98+
99+
Favor the present tense. The present tense is usually clearer and shorter:
100+
101+
✅ Present: The client then sends a request to the server.
102+
❌ Future: The client will then send a request to the server.
103+
104+
Avoid repetition. Repetition adds more cognitive load and possibilities for different
105+
parts of the specification to diverge in their meaning.

0 commit comments

Comments
 (0)