GraphQL project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
GraphQL
Technical writer:
carolstran
Project name:
Create FAQ resource
Project length:
Standard length (3 months)

Project description

Learning a new technology is never easy - and it comes with a lot of questions. With GraphQL, the project has evolved enough that, for the most part, the information is out there. It’s just a matter of finding it because that information is scattered through various resources and programming communities.

Something that could be an instrumental improvement for GraphQL learners would be a central Frequently Asked Questions (FAQ) section. This is currently missing from graphql.org and leads to questions that are either constantly repeated or left unanswered.

This new FAQ section will be integrated into the graphql.org website and contain sections related to:

  • GraphQL history and internals

    • What is the GraphQL Foundation?
    • When and why was GraphQL created?
    • What are the best resources for getting started?

  • GraphQL basics

    • What is the difference between GraphQL and REST/SQL/etc?
    • What are the best use cases for GraphQL?
    • Is GraphQL only for React developers?

  • Advanced GraphQL concepts

    • How can you do server-side caching with GraphQL?
    • Does GraphQL support offline usage?
    • How can you test your GraphQL API?

  • Specification

    • How can I contribute to the specification?
    • What’s the best way to follow the specification releases?

And likely more sections to come. The above questions are potential examples. They’re also all ones that I have been asked by colleagues who are learning or after giving a conference talk related to GraphQL.

The questions for the FAQ will be sourced through various areas of the Internet and then later sorted and prioritized. Some of these areas include:

  • StackOverflow
  • GitHub issues (in the GraphQL organization, How To GraphQL and beyond)
  • Twitter
  • Conversations with prominent GraphQL instructors
  • GraphQL-related product pages
  • Quora

In addition to succinct and helpful content, the final FAQ page will be built with UX and accessibility in mind.