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 Slide

  2. @carolstran

    View Slide

  3. @carolstran
    graph.cool

    View Slide

  4. @carolstran

    View Slide

  5. @carolstran

    View Slide

  6. @carolstran

    View Slide

  7. @carolstran

    View Slide

  8. @carolstran

    View Slide

  9. @carolstran

    View Slide

  10. @carolstran

    View Slide

  11. @carolstran

    View Slide

  12. @carolstran

    View Slide

  13. GraphQL
    @carolstran

    View Slide

  14. GraphQL
    @carolstran

    View Slide

  15. @carolstran

    View Slide

  16. @carolstran

    View Slide

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

    View Slide

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

    View Slide

  19. @carolstran
    graphql.org

    View Slide

  20. @carolstran

    View Slide

  21. @carolstran

    View Slide

  22. @carolstran

    View Slide

  23. @carolstran
    graphql.org

    View Slide

  24. @carolstran
    graphql.org

    View Slide

  25. @carolstran
    graphql.org/learn

    View Slide

  26. @carolstran
    graphql.org/learn

    View Slide

  27. @carolstran

    View Slide

  28. @carolstran

    View Slide

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

    View Slide

  30. @carolstran
    gatsbyjs.org

    View Slide

  31. @carolstran

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  36. “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 Slide

  37. …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 Slide

  38. “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 Slide

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

    View Slide

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

    View Slide

  41. @carolstran
    bit.ly/graphql-def

    View Slide

  42. @carolstran

    View Slide

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

    View Slide

  44. @carolstran
    graphql.org/learn

    View Slide

  45. @carolstran
    graphql.org/learn

    View Slide

  46. @carolstran
    graphql.org/code

    View Slide

  47. Assumed knowledge
    and specific terminology
    Problem
    @carolstran

    View Slide

  48. @carolstran
    Everyone is a beginner
    at some point

    View Slide

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

    View Slide

  50. @carolstran
    bit.ly/graphql-glossary

    View Slide

  51. @carolstran
    bit.ly/fb-graphapi

    View Slide

  52. Quick wins
    some short documentation tips
    @carolstran

    View Slide

  53. Be confident with your
    definitions
    Quick win
    @carolstran

    View Slide

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

    View Slide

  55. Be transparent about
    any downfalls
    Quick win
    @carolstran

    View Slide

  56. More resources
    for learning GraphQL and beyond
    @carolstran

    View Slide

  57. HowToGraphQL.com
    Resource
    @carolstran

    View Slide

  58. @carolstran
    howtographql.com

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  64. @carolstran
    graphql.org/community

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  68. @carolstran
    bit.ly/javascript-monads

    View Slide

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

    View Slide