diff --git a/BLOG_STYLE_GUIDE.md b/BLOG_STYLE_GUIDE.md new file mode 100644 index 0000000000..8c75fa6f85 --- /dev/null +++ b/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 (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! πŸŽ‰ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06b99b5de1..38d215bb86 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! 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.