Skip to content

Add BLOG_STYLE_GUIDE.md #2032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: source
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions BLOG_STYLE_GUIDE.md
Original file line number Diff line number Diff line change
@@ -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 (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").

---

## ✅ 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 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.

---

Thank you for contributing to the GraphQL Blog! 🎉
7 changes: 7 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand Down
Loading