Skip to content

Commit

Permalink
Add tone of voice and definitions to the style guide
Browse files Browse the repository at this point in the history
  • Loading branch information
martinbonnin committed Feb 25, 2025
1 parent 7073e3a commit e1056fc
Showing 1 changed file with 21 additions and 0 deletions.
21 changes: 21 additions & 0 deletions STYLE_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,3 +82,24 @@ MyAlgorithm(argOne, argTwo):
- Let {something} be {true}.
- Return {something}.
```

## Definitions

For important terms, use [Spec Markdown definition paragraphs](https://spec-md.com/#sec-Definition-Paragraph).

Definition paragraphs start with `::` and addsthe matching italicized term to the
[specification index](https://spec.graphql.org/draft/#index), making it easy to
reference them.

## Tone of voice

The GraphQL specification is a reference document and should use neutral and
descriptive tone of voice.

Favor the present tense. The present tense is usually clearer and shorter:

✅ Present: The client then sends a request to the server.
❌ Future: The client will then send a request to the server.

Avoid repetition. Repetition adds more cognitive load and possibilities for different
parts of the specification to diverge in their meaning.

0 comments on commit e1056fc

Please sign in to comment.