From e1056fc03b262507d42ad113bbf804969b3f6948 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Tue, 25 Feb 2025 10:20:31 +0100 Subject: [PATCH 1/4] Add tone of voice and definitions to the style guide --- STYLE_GUIDE.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 7ee0e2915..a81e2d98b 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -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. From 1e198e689b50c221eab72f95d6b9999f994ee367 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Tue, 25 Feb 2025 11:25:17 +0100 Subject: [PATCH 2/4] Update STYLE_GUIDE.md Co-authored-by: Benjie --- STYLE_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index a81e2d98b..0b024e6a6 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -87,7 +87,7 @@ MyAlgorithm(argOne, argTwo): 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 +Definition paragraphs start with `::` and add the matching italicized term to the [specification index](https://spec.graphql.org/draft/#index), making it easy to reference them. From 6578a305b77acfdc87eb1eac2df45953806af1a3 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Tue, 25 Feb 2025 11:25:55 +0100 Subject: [PATCH 3/4] remove tone of voice --- STYLE_GUIDE.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 0b024e6a6..fa61e7ab3 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -90,16 +90,3 @@ For important terms, use [Spec Markdown definition paragraphs](https://spec-md.c Definition paragraphs start with `::` and add the 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. From 540392cfb6d76abeadc62bdefaf9d793d495535b Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Tue, 25 Feb 2025 14:15:54 +0100 Subject: [PATCH 4/4] format --- STYLE_GUIDE.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index fa61e7ab3..f3156a41f 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -85,8 +85,9 @@ MyAlgorithm(argOne, argTwo): ## Definitions -For important terms, use [Spec Markdown definition paragraphs](https://spec-md.com/#sec-Definition-Paragraph). +For important terms, use +[Spec Markdown definition paragraphs](https://spec-md.com/#sec-Definition-Paragraph). -Definition paragraphs start with `::` and add the matching italicized term to the -[specification index](https://spec.graphql.org/draft/#index), making it easy to -reference them. +Definition paragraphs start with `::` and add the matching italicized term to +the [specification index](https://spec.graphql.org/draft/#index), making it easy +to reference them.