Skip to content

Latest commit

 

History

History
82 lines (54 loc) · 3.36 KB

BLOG_STYLE_GUIDE.md

File metadata and controls

82 lines (54 loc) · 3.36 KB

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 or a draft by opening a pull request.

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).

Example content:

  • Announcements: events, new versions of GraphQL tools or specifications, 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.

📚 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! 🎉