Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Life is hard and so is learning GraphQL

Life is hard and so is learning GraphQL

A talk focused on the trials and tribulations of learning GraphQL, but how documentation can help.

Current deck from: ReactJS Girls Conference
Recording: bit.ly/graphql-finland

Carolyn Stransky

May 03, 2019
Tweet

More Decks by Carolyn Stransky

Other Decks in Technology

Transcript

  1. Life is hard
    and so is learning GraphQL
    @carolstran

    View full-size slide

  2. @carolstran
    graph.cool

    View full-size slide

  3. GraphQL
    @carolstran

    View full-size slide

  4. GraphQL
    @carolstran

    View full-size slide

  5. Go to GraphiQL and
    “try it out”
    @carolstran
    bit.ly/graphiql-demo

    View full-size slide

  6. Work your way through
    the documentation
    @carolstran
    graphql.org

    View full-size slide

  7. @carolstran
    graphql.org

    View full-size slide

  8. @carolstran
    graphql.org

    View full-size slide

  9. @carolstran
    graphql.org

    View full-size slide

  10. @carolstran
    graphql.org/learn

    View full-size slide

  11. @carolstran
    graphql.org/learn

    View full-size slide

  12. @carolstran
    Anyone who encounters
    GraphQL, needs to be able
    to understand it

    View full-size slide

  13. @carolstran
    gatsbyjs.org

    View full-size slide

  14. The problems
    and what we can do about it
    @carolstran

    View full-size slide

  15. Just because GraphQL is “self-
    documenting," doesn’t mean
    you should stop writing docs
    @carolstran
    Problem

    View full-size slide

  16. @carolstran
    bit.ly/github-gql-api

    View full-size slide

  17. @carolstran
    bit.ly/github-gql-api

    View full-size slide

  18. “This type of documentation is great after
    you understand the domain area and the
    business cases and you’ve built some
    confidence making queries and mutations…
    @carolstran
    — Andrew Johnston
    bit.ly/andrew-api-docs

    View full-size slide

  19. …but without more detailed
    documentation that covers the
    conceptual materials, you’re not
    going to get there.”
    @carolstran
    — Andrew Johnston
    bit.ly/andrew-api-docs

    View full-size slide

  20. “Documenting API endpoints explains
    how individual tools work, explaining how
    to use those tools together is a whole
    other area of documentation effort. ”
    @carolstran
    — Chris Ward
    bit.ly/documenting-graphql

    View full-size slide

  21. @carolstran
    gatsbyjs.org/docs/querying-with-graphql/

    View full-size slide

  22. GraphQL is dominated by
    the JavaScript community
    @carolstran
    Problem

    View full-size slide

  23. @carolstran
    bit.ly/graphql-def

    View full-size slide

  24. @carolstran
    JavaScript
    TypeScript
    Ruby
    PHP
    Python
    Java
    C/C++
    Swift
    .NET
    Erlang
    Elixir
    Haskell
    Rust
    Go
    Scala
    Clojure
    R
    (and more)

    View full-size slide

  25. @carolstran
    graphql.org/learn

    View full-size slide

  26. @carolstran
    graphql.org/learn

    View full-size slide

  27. @carolstran
    graphql.org/code

    View full-size slide

  28. Assumed knowledge
    and specific terminology
    Problem
    @carolstran

    View full-size slide

  29. @carolstran
    Everyone is a beginner
    at some point

    View full-size slide

  30. Listing pre-reqs for a tutorial
    will help prevent headaches
    @carolstran

    View full-size slide

  31. @carolstran
    bit.ly/graphql-glossary

    View full-size slide

  32. @carolstran
    bit.ly/fb-graphapi

    View full-size slide

  33. Quick wins
    some short documentation tips
    @carolstran

    View full-size slide

  34. Be confident with your
    definitions
    Quick win
    @carolstran

    View full-size slide

  35. Don’t integrate tools or
    services without explanation
    Quick win
    @carolstran

    View full-size slide

  36. Be transparent about
    any downfalls
    Quick win
    @carolstran

    View full-size slide

  37. More resources
    for learning GraphQL and beyond
    @carolstran

    View full-size slide

  38. HowToGraphQL.com
    Resource
    @carolstran

    View full-size slide

  39. @carolstran
    howtographql.com

    View full-size slide

  40. A Frontend Developer’s
    Guide to GraphQL
    Resource
    @carolstran
    github.com/peggyrayzis/guide-to-graphql

    View full-size slide

  41. @carolstran
    css-tricks.com/front-end-developers-guide-graphql/

    View full-size slide

  42. GitHub's GraphQL API
    Resource
    @carolstran
    bit.ly/github-gql-api

    View full-size slide

  43. @carolstran
    bit.ly/github-gql-api

    View full-size slide

  44. Community Resources on
    official GraphQL docs
    Resource
    @carolstran
    graphql.org/community

    View full-size slide

  45. @carolstran
    graphql.org/community

    View full-size slide

  46. https://so-you-want-to-learn-
    graphql.netlify.com/
    Resource
    @carolstran
    github.com/carolstran/so-you-want-to-learn-graphql

    View full-size slide

  47. @carolstran
    github.com/carolstran/so-you-want-to-learn-graphql

    View full-size slide

  48. One last thing
    (but actually, I promise)
    @carolstran

    View full-size slide

  49. @carolstran
    bit.ly/javascript-monads

    View full-size slide

  50. @carolstran
    Please don’t let GraphQL
    become the new monads

    View full-size slide