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


Carolyn Stransky

May 03, 2019


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

  2. @carolstran

  3. @carolstran

  4. @carolstran

  5. @carolstran

  6. @carolstran

  7. @carolstran

  8. @carolstran

  9. @carolstran

  10. @carolstran

  11. @carolstran

  12. @carolstran

  13. GraphQL @carolstran

  14. GraphQL @carolstran

  15. @carolstran

  16. @carolstran

  17. Go to GraphiQL and “try it out” @carolstran

  18. Work your way through the documentation @carolstran

  19. @carolstran

  20. @carolstran

  21. @carolstran

  22. @carolstran

  23. @carolstran

  24. @carolstran

  25. @carolstran

  26. @carolstran

  27. @carolstran

  28. @carolstran

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

    understand it
  30. @carolstran

  31. @carolstran

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

  33. Just because GraphQL is “self- documenting," doesn’t mean you should

    stop writing docs @carolstran Problem
  34. @carolstran

  35. @carolstran

  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
  37. …but without more detailed documentation that covers the conceptual materials,

    you’re not going to get there.” @carolstran — Andrew Johnston
  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
  39. @carolstran

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

  41. @carolstran

  42. @carolstran

  43. @carolstran JavaScript TypeScript Ruby PHP Python Java C/C++ Swift .NET

    Erlang Elixir Haskell Rust Go Scala Clojure R (and more)
  44. @carolstran

  45. @carolstran

  46. @carolstran

  47. Assumed knowledge and specific terminology Problem @carolstran

  48. @carolstran Everyone is a beginner at some point

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

  50. @carolstran

  51. @carolstran

  52. Quick wins some short documentation tips @carolstran

  53. Be confident with your definitions Quick win @carolstran

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

  55. Be transparent about any downfalls Quick win @carolstran

  56. More resources for learning GraphQL and beyond @carolstran

  57. Resource @carolstran

  58. @carolstran

  59. A Frontend Developer’s Guide to GraphQL Resource @carolstran

  60. @carolstran

  61. GitHub's GraphQL API Resource @carolstran

  62. @carolstran

  63. Community Resources on official GraphQL docs Resource @carolstran

  64. @carolstran

  65. https://so-you-want-to-learn- Resource @carolstran

  66. @carolstran

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

  68. @carolstran

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