From bc4ff38c84c1af70d7f662246bfa856fa77c254a Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Fri, 20 Jun 2025 15:50:27 +0200 Subject: [PATCH 1/8] Mention the blog post in CONTRIBUTING.md --- CONTRIBUTING.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06b99b5de1..c2635c0a87 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,7 @@ There are many ways to get involved. Follow this guide and feel free to [reach o - [Add a resource to the Community page](#add-a-resource-to-the-community-page) - [Add a question to the FAQ](#add-a-question-to-the-faq) - [Write a new section or guide](#write-a-new-section-or-guide) + - [Add a blog post](#add-a-blog-post) - [Making changes to the code](#making-changes-to-the-code) - [Browser support](#browser-support) - [Contributing something else](#contributing-something-else) @@ -149,6 +150,12 @@ Then, use our [development guide](#development-guide) to determine where your ne Once it's ready for review, please [open a pull request](https://github.com/graphql/graphql.github.io/pulls). +### Add a blog post + +This repository holds the [graphql.org blog](https://graphql.org/blog/) at [source/src/pages/blog](https://github.com/graphql/graphql.github.io/tree/source/src/pages/blog). Blog posts may contain announcements, news, best practices and more. + +Contributions are very welcome! + ## Making changes to the code Before diving into any code updates, please [open an issue](https://github.com/graphql/graphql.github.io/issues/new) describing the change(s) you'd like to make. From 092ed7e20aa86927af36700b56dc0942a018cc09 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Fri, 20 Jun 2025 16:13:30 +0200 Subject: [PATCH 2/8] Add BLOG_STYLE_GUIDE.md --- BLOG_STYLE_GUIDE.md | 92 +++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 +- 2 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 BLOG_STYLE_GUIDE.md diff --git a/BLOG_STYLE_GUIDE.md b/BLOG_STYLE_GUIDE.md new file mode 100644 index 0000000000..cd77437dcb --- /dev/null +++ b/BLOG_STYLE_GUIDE.md @@ -0,0 +1,92 @@ +# BLOG_STYLE_GUIDE.md + +## GraphQL Blog Content Style Guide + +Welcome to the GraphQL Blog Style Guide! This document outlines best practices and standards for writing engaging, informative, and technically accurate content for our audience. + +--- + +## ✍️ General Writing Principles + +- **Audience First**: Assume the reader has a technical background (developers, engineers) but may be new to GraphQL concepts. +- **Clarity is Key**: Prioritize clear, concise explanations over jargon. Break down complex ideas with examples. +- **Vendor neutral**: The GraphQL Blog is about GraphQL as a technology. Vendor specific content and personal promotion doesn't belong in the GraphQL blog. + +## ℹ️ Content + +The GraphQL blog welcomes contributions. Anyone may submit a blog post idea by [opening an issue](https://github.com/graphql/graphql.github.io/issues/new) or a draft by [opening a pull request](https://github.com/graphql/graphql.github.io/pulls). + +Maintainers are responsible for approving and merging the pull requests. + +Example content: +- Announcements: events, new versions of [GraphQL tools or specifications](https://github.com/orgs/graphql/repositories), updates about the GraphQL foundation, collaborations, etc... +- Best practices: share learnings and make the best of GraphQL. +- Case studies: explain how GraphQL helped solve a problem. +- Technical updates: broadcast an update about discussions happening in a working group. +- etc... + +This list is non-exhaustive. If there is something you would like to see on the GraphQL blog, [open an issue for discussion](https://github.com/graphql/graphql.github.io/issues/new). + +--- + +## 📚 Structure + +### Title +- Clear, concise, and descriptive. +- Avoid clickbait. Example: + ✅ "Understanding GraphQL Subscriptions" + ❌ "This One GraphQL Trick Will Blow Your Mind" + +### Introduction +- Hook the reader in 1–2 sentences. +- Set clear expectations about what the post covers and who it's for. + +### Body +- Use clear headers (`##`, `###`) to organize sections. +- Limit paragraphs to 3–5 sentences. +- Use bullet points or numbered lists for step-by-step content. +- Include **code samples** where relevant (see Code Style below). +- Use callouts for **tips**, **warnings**, or **best practices**. + +### Conclusion +- Summarize key takeaways. +- Link to related resources, docs, or posts. +- Include a call to action if applicable (e.g., "Try it out", "Join the discussion"). + +--- + +## 🧑‍💻 Code Style + +- Use fenced code blocks with language identifiers: + 
+  \`\`\`graphql
+  query GetUser {
+    user(id: "1") {
+      name
+    }
+  }
+  \`\`\`
+
+ +- Avoid overly long code samples—focus on what supports the topic. +- Explain what the code is doing either before or after the block. +- Stick to consistent naming conventions (e.g., `getUser`, `createPostMutation`). +--- + +## ✅ Do + +- Cite sources if you reference third-party tools or documentation. +- Avoid assumptions: don’t assume the reader knows your stack. +- Use inclusive language: prefer "you/the user" over gendered or assumptive terms. +- Use present tense. + +## ❌ Don't + +- Overuse of metaphors. Use them sparingly to aid understanding. +- Outdated examples or deprecated syntax. +- Avoid passive voice when possible. +- Avoid future tense. + +--- + +Thank you for contributing to the GraphQL Blog! 🎉 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2635c0a87..4a656557c3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -154,7 +154,7 @@ Once it's ready for review, please [open a pull request](https://github.com/grap This repository holds the [graphql.org blog](https://graphql.org/blog/) at [source/src/pages/blog](https://github.com/graphql/graphql.github.io/tree/source/src/pages/blog). Blog posts may contain announcements, news, best practices and more. -Contributions are very welcome! +Contributions are very welcome! Please see the [BLOG_STYLE_GUIDE](BLOG_STYLE_GUIDE.md) for more information. ## Making changes to the code From a9c0a96b28cf12df944ca28b7d5d67c4db50796f Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Fri, 20 Jun 2025 16:17:21 +0200 Subject: [PATCH 3/8] formating --- BLOG_STYLE_GUIDE.md | 12 +++++++++--- CONTRIBUTING.md | 2 +- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/BLOG_STYLE_GUIDE.md b/BLOG_STYLE_GUIDE.md index cd77437dcb..ce3b0b58cb 100644 --- a/BLOG_STYLE_GUIDE.md +++ b/BLOG_STYLE_GUIDE.md @@ -10,15 +10,16 @@ Welcome to the GraphQL Blog Style Guide! This document outlines best practices a - **Audience First**: Assume the reader has a technical background (developers, engineers) but may be new to GraphQL concepts. - **Clarity is Key**: Prioritize clear, concise explanations over jargon. Break down complex ideas with examples. -- **Vendor neutral**: The GraphQL Blog is about GraphQL as a technology. Vendor specific content and personal promotion doesn't belong in the GraphQL blog. +- **Vendor neutral**: The GraphQL Blog is about GraphQL as a technology. Vendor specific content and personal promotion doesn't belong in the GraphQL blog. ## ℹ️ Content -The GraphQL blog welcomes contributions. Anyone may submit a blog post idea by [opening an issue](https://github.com/graphql/graphql.github.io/issues/new) or a draft by [opening a pull request](https://github.com/graphql/graphql.github.io/pulls). +The GraphQL blog welcomes contributions. Anyone may submit a blog post idea by [opening an issue](https://github.com/graphql/graphql.github.io/issues/new) or a draft by [opening a pull request](https://github.com/graphql/graphql.github.io/pulls). Maintainers are responsible for approving and merging the pull requests. Example content: + - Announcements: events, new versions of [GraphQL tools or specifications](https://github.com/orgs/graphql/repositories), updates about the GraphQL foundation, collaborations, etc... - Best practices: share learnings and make the best of GraphQL. - Case studies: explain how GraphQL helped solve a problem. @@ -32,16 +33,19 @@ This list is non-exhaustive. If there is something you would like to see on the ## 📚 Structure ### Title + - Clear, concise, and descriptive. - Avoid clickbait. Example: ✅ "Understanding GraphQL Subscriptions" ❌ "This One GraphQL Trick Will Blow Your Mind" ### Introduction + - Hook the reader in 1–2 sentences. - Set clear expectations about what the post covers and who it's for. ### Body + - Use clear headers (`##`, `###`) to organize sections. - Limit paragraphs to 3–5 sentences. - Use bullet points or numbered lists for step-by-step content. @@ -49,6 +53,7 @@ This list is non-exhaustive. If there is something you would like to see on the - Use callouts for **tips**, **warnings**, or **best practices**. ### Conclusion + - Summarize key takeaways. - Link to related resources, docs, or posts. - Include a call to action if applicable (e.g., "Try it out", "Join the discussion"). @@ -71,6 +76,7 @@ This list is non-exhaustive. If there is something you would like to see on the - Avoid overly long code samples—focus on what supports the topic. - Explain what the code is doing either before or after the block. - Stick to consistent naming conventions (e.g., `getUser`, `createPostMutation`). + --- ## ✅ Do @@ -89,4 +95,4 @@ This list is non-exhaustive. If there is something you would like to see on the --- -Thank you for contributing to the GraphQL Blog! 🎉 \ No newline at end of file +Thank you for contributing to the GraphQL Blog! 🎉 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a656557c3..38d215bb86 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -152,7 +152,7 @@ Once it's ready for review, please [open a pull request](https://github.com/grap ### Add a blog post -This repository holds the [graphql.org blog](https://graphql.org/blog/) at [source/src/pages/blog](https://github.com/graphql/graphql.github.io/tree/source/src/pages/blog). Blog posts may contain announcements, news, best practices and more. +This repository holds the [graphql.org blog](https://graphql.org/blog/) at [source/src/pages/blog](https://github.com/graphql/graphql.github.io/tree/source/src/pages/blog). Blog posts may contain announcements, news, best practices and more. Contributions are very welcome! Please see the [BLOG_STYLE_GUIDE](BLOG_STYLE_GUIDE.md) for more information. From fe1a9ce717aaab04f7ad1f026e5db2af6fec82f6 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 23 Jun 2025 14:43:05 +0200 Subject: [PATCH 4/8] Update BLOG_STYLE_GUIDE.md Co-authored-by: Benjie --- BLOG_STYLE_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BLOG_STYLE_GUIDE.md b/BLOG_STYLE_GUIDE.md index ce3b0b58cb..e8758f6cec 100644 --- a/BLOG_STYLE_GUIDE.md +++ b/BLOG_STYLE_GUIDE.md @@ -8,7 +8,7 @@ Welcome to the GraphQL Blog Style Guide! This document outlines best practices a ## ✍️ General Writing Principles -- **Audience First**: Assume the reader has a technical background (developers, engineers) but may be new to GraphQL concepts. +- **Audience First**: Think about who the audience of your post is. For release notes, you can assume some familiarity with the project. For other technical posts, you should typically assume the reader has a technical background (developers, engineers) but may be new to GraphQL concepts. For broader posts (case studies, events, grants, reports) avoid overly technical language. - **Clarity is Key**: Prioritize clear, concise explanations over jargon. Break down complex ideas with examples. - **Vendor neutral**: The GraphQL Blog is about GraphQL as a technology. Vendor specific content and personal promotion doesn't belong in the GraphQL blog. From 7f250d08930c653e442b293fc51c8fd62545cdee Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 23 Jun 2025 14:43:18 +0200 Subject: [PATCH 5/8] Update BLOG_STYLE_GUIDE.md Co-authored-by: Benjie --- BLOG_STYLE_GUIDE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/BLOG_STYLE_GUIDE.md b/BLOG_STYLE_GUIDE.md index e8758f6cec..b0566d4b43 100644 --- a/BLOG_STYLE_GUIDE.md +++ b/BLOG_STYLE_GUIDE.md @@ -17,6 +17,7 @@ Welcome to the GraphQL Blog Style Guide! This document outlines best practices a The GraphQL blog welcomes contributions. Anyone may submit a blog post idea by [opening an issue](https://github.com/graphql/graphql.github.io/issues/new) or a draft by [opening a pull request](https://github.com/graphql/graphql.github.io/pulls). Maintainers are responsible for approving and merging the pull requests. +When merging a blog post, they should also schedule an announcement on our social channels (at time of writing this is managed via [Typefully](https://typefully.com)). Example content: From db4cd92b0305c9bbf004a91cc9978b54bcb492ee Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 23 Jun 2025 14:49:54 +0200 Subject: [PATCH 6/8] reshuffle the "audience first" part a bit --- BLOG_STYLE_GUIDE.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/BLOG_STYLE_GUIDE.md b/BLOG_STYLE_GUIDE.md index b0566d4b43..9c5572c92f 100644 --- a/BLOG_STYLE_GUIDE.md +++ b/BLOG_STYLE_GUIDE.md @@ -8,7 +8,7 @@ Welcome to the GraphQL Blog Style Guide! This document outlines best practices a ## ✍️ General Writing Principles -- **Audience First**: Think about who the audience of your post is. For release notes, you can assume some familiarity with the project. For other technical posts, you should typically assume the reader has a technical background (developers, engineers) but may be new to GraphQL concepts. For broader posts (case studies, events, grants, reports) avoid overly technical language. +- **Audience First**: Think about who the audience of your post is. - **Clarity is Key**: Prioritize clear, concise explanations over jargon. Break down complex ideas with examples. - **Vendor neutral**: The GraphQL Blog is about GraphQL as a technology. Vendor specific content and personal promotion doesn't belong in the GraphQL blog. @@ -43,7 +43,10 @@ This list is non-exhaustive. If there is something you would like to see on the ### Introduction - Hook the reader in 1–2 sentences. -- Set clear expectations about what the post covers and who it's for. +- Set clear expectations about what the post covers and who it's for: + - open source users of a given project (release notes, updates,...) are probably already familiar with the tool. + - technical users (best practices, working group updates) have a technical background but may be new to GraphQL concepts. + - larger audience (case studies, events, grants, reports) may not necessarily have a technical background but still be interested in latest GraphQL content. ### Body From 5c85aca85d1fef7a6d4e570576273f21cb70c8c1 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 23 Jun 2025 14:52:42 +0200 Subject: [PATCH 7/8] remove code paragraph --- BLOG_STYLE_GUIDE.md | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/BLOG_STYLE_GUIDE.md b/BLOG_STYLE_GUIDE.md index 9c5572c92f..31d21af603 100644 --- a/BLOG_STYLE_GUIDE.md +++ b/BLOG_STYLE_GUIDE.md @@ -64,25 +64,6 @@ This list is non-exhaustive. If there is something you would like to see on the --- -## 🧑‍💻 Code Style - -- Use fenced code blocks with language identifiers: - 
-  \`\`\`graphql
-  query GetUser {
-    user(id: "1") {
-      name
-    }
-  }
-  \`\`\`
-
- -- Avoid overly long code samples—focus on what supports the topic. -- Explain what the code is doing either before or after the block. -- Stick to consistent naming conventions (e.g., `getUser`, `createPostMutation`). - ---- - ## ✅ Do - Cite sources if you reference third-party tools or documentation. From 052acf7e2ab01f6d6383c4d82204270e9cefdc72 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 23 Jun 2025 14:54:52 +0200 Subject: [PATCH 8/8] reshuffle dos and donts --- BLOG_STYLE_GUIDE.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/BLOG_STYLE_GUIDE.md b/BLOG_STYLE_GUIDE.md index 31d21af603..8c75fa6f85 100644 --- a/BLOG_STYLE_GUIDE.md +++ b/BLOG_STYLE_GUIDE.md @@ -67,16 +67,15 @@ This list is non-exhaustive. If there is something you would like to see on the ## ✅ Do - Cite sources if you reference third-party tools or documentation. -- Avoid assumptions: don’t assume the reader knows your stack. - Use inclusive language: prefer "you/the user" over gendered or assumptive terms. - Use present tense. ## ❌ Don't -- Overuse of metaphors. Use them sparingly to aid understanding. -- Outdated examples or deprecated syntax. -- Avoid passive voice when possible. -- Avoid future tense. +- Don’t assume the reader knows your stack. +- Don't overuse of metaphors. Use them sparingly to aid understanding. +- Don't overuse passive voice. Active voice often brings more clarity. +- Don't overuse future tense. The present tense often brings more clarity. ---