Add BLOG_STYLE_GUIDE.md

BLOG_STYLE_GUIDE.md

@@ -0,0 +1,98 @@
+# 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:
+  <pre>
+  \`\`\`graphql
+  query GetUser {
+    user(id: "1") {
+      name
+    }
+  }
+  \`\`\`
+  </pre>
+
+- 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! 🎉

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! Please see the [BLOG_STYLE_GUIDE](BLOG_STYLE_GUIDE.md) for more information.
+
 ## 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.