-
Notifications
You must be signed in to change notification settings - Fork 1.5k
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
martinbonnin
wants to merge
8
commits into
graphql:source
Choose a base branch
from
martinbonnin:style-guide
base: source
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Add BLOG_STYLE_GUIDE.md #2032
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
bc4ff38
Mention the blog post in CONTRIBUTING.md
martinbonnin 092ed7e
Add BLOG_STYLE_GUIDE.md
martinbonnin a9c0a96
formating
martinbonnin fe1a9ce
Update BLOG_STYLE_GUIDE.md
martinbonnin 7f250d0
Update BLOG_STYLE_GUIDE.md
martinbonnin db4cd92
reshuffle the "audience first" part a bit
martinbonnin 5c85aca
remove code paragraph
martinbonnin 052acf7
reshuffle dos and donts
martinbonnin File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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! 🎉 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.