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

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