Merge remote-tracking branch 'upstream/source' into source

Author: hasparus

BLOG_STYLE_GUIDE.md

@@ -0,0 +1,82 @@
+# 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**: 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.
+
+## ℹ️ 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.
+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:
+
+- 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:
+  - 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
+
+- 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.
+- 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").
+
+---
+
+## ✅ Do
+
+- Cite sources if you reference third-party tools or documentation.
+- Use inclusive language: prefer "you/the user" over gendered or assumptive terms.
+- Use present tense.
+
+## ❌ Don't
+
+- Don’t assume the reader knows your stack.
+- Don't overuse 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.
+
+---
+
+Thank you for contributing to the GraphQL Blog! 🎉

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