Is GraphQL really self-documenting?

A conference talk discussing whether GraphQL is self-documenting.

Discusses self-documenting code, the origins of GraphQL, the importance of naming and descriptions in GraphQL and how you can document it.

Location: API the Docs at the Barbican Centre in London.

Transcript

1. Is GraphQL really self-documenting? James Scott Technical Writer at Moogsoft @jwscott22
2. @jwscott22
3. “A common mistake people make when trying to design something completely foolproof is to underestimate the ingenuity of complete fools.” - Douglas Adams @jwscott22
4. 1. What is the problem? 
 2. What is GraphQL?
 3. What is the answer? Agenda @jwscott22
5. @jwscott22
6. What does “self-documenting” mean? Written and structured in such a way it can be understood without documentation or prior-knowledge. @jwscott22
7. Subjectivity with images @jwscott22
8. @jwscott22 Subjectivity with words query{ second } query{ number } query{ subject } 1. Numerical value 2. A quantity or amount 3. To count (verb) 4. More numb 1. Topic 2. The noun in a sentence 3. Under some authority 1. Unit of time 2. Number 2 in a sequence
9. @jwscott22 “Self-documenting code is a unicorn”
10. @jwscott22 Others have said similar…
11. 1. I made an object/function with a specific use 2. I gave it a name that explains the specific use 3. Doesn’t need docs because it’s obvious how it works. @jwscott22 What it boils down to…
12. 1. What is the problem? 
 2. What is GraphQL?
 3. What is the answer? Agenda @jwscott22
13. “…I think the biggest mistake we made as a company is betting too much on HTML5 as opposed to native… because it just wasn’t there… We burned two years. That's really painful.” - Mark Zuckerberg, Facebook CEO Origins of GraphQL @jwscott22
14. Founders of GraphQL Lee Byron Nick Schrock Dan Schafer Mobile app dev team lead Creator of SuperGraph Facebook News Feed engineer
15. GraphQL at Facebook iOS News Feed iOS Messenger Ads Manager Facebook Lite iPad Pages Android Feed @jwscott22
16. Relay GraphQL @jwscott22 Open-sourcing of GraphQL
17. @jwscott22
18. So what is GraphQL? • Data query language for APIs • Can retrieve data using a query • Can modify data using a mutation • Client specifies exact data they want • Result is no over-fetching of data • Exposes a single endpoint to do all of these things. @jwscott22
19. Thinking in Graphs @jwscott22 Graph theory!?
20. A Graph = A Tree @jwscott22 Member Book “Frodo” “Sam” “Pippin” “Merry” “Aragorn” “Boromir” “Gimli” “Legolas” “Gandalf” Hobbit Man Dwarf Elf Istari Man Hobbit Hobbit Hobbit “The Fellowship of the Ring” title inFellowship race race race race race race race race race name name name name name name
21. What does GraphQL look like? @jwscott22 { hero { name } } { "data" : { "hero" : { "name" : "Frodo" } } }
22. Query to return related objects @jwscott22 { hero { name companion { name } } } { "data" : { "hero" : { "name" : "Frodo", "companion" : [ { "name" : "Sam" }, { "name" : "Gandalf" }, { "name" : "Legolas" }, { "name" : "Gimli" }, { "name" : "Aragorn" }, { "name" : "Merry" }, { "name" : "Pippin" } ] } } }
23. Over-fetching @jwscott22 $ curl https://localhost/lotr/v1/getInfo?characterid=6 [ { "character":{ "name":"Aragorn", "alias":"Strider", "title":"King of the Reunited Kingdom", "height":"1.98", "house":"Telcontar", "weapon":"Anduril", "race":"Human", "gender":"Male", "age":"210", "wife":"Arwen", "father":"Arathorn", "mother":"Gilraen", } } ]
24. Query using arguments @jwscott22 { character(id:"6") { name height age } } { "data" : { "character" : { "name" : "Aragorn" "height" : 1.98 "age" : 210 } }
25. GraphQL mutations @jwscott22 mutation { addCategory( id:1, name: "hobbits", characters: [1, 2, 7, 8]) { name characters { name } } } { "data" : { "addCategory": { "name": "hobbits", "characters": [ { "name": "Frodo" }, { "name": "Sam" }, { "name": "Merry" }, { "name": "Pippin" } ] } } }
26. GraphiQL (“Graphical”) @jwscott22 Imagine landing here with no prior knowledge of: • What the schema looks like • How to structure a query • What queries are even possible!
27. @jwscott22
28. @jwscott22 query { user { jwscott22 { name } } } { "data" : null, "errors": [ { "message": "Field 'user' is missing required arguments: login", "locations": [ { "line": 2, "column": 3} ] }, { "message": "Field 'jwscott22' doesn't exist on type 'User'", "locations": [ { "line": 3, "column": 5} ] } ] } query { user(login:jwscott22) { name avatarUrl location } } }
29. Scenario 1: Assumed Knowledge! @jwscott22
30. @jwscott22 Scenario 2: ‘Self descriptive’?
31. 1. What is the problem? 
 2. What is GraphQL?
 3. What is the answer? Agenda @jwscott22
32. <Insert_sensible_name> “Naming is Super Important…” @jwscott22 “Would a new engineer understand this?”
33. @jwscott22 “Naming things that adhere closely to what those things do is really important to make this experience work…”
34. What does the spec say? @jwscott22
35. Hi Lee, I’m writing a blog about GraphQL. Could I ask you some questions over video chat at some point? James Hi James! Sorry for the delay. I’d be happy to do an interview with you. Lee @jwscott22
36. @jwscott22 Advice from the co-creator
37. - Lee Byron, co-creator of GraphQL “If there's no documentation, it doesn't matter how good the API is […] If you do that wrong, people aren't going to be able to use it…” @jwscott22
38. Filling the “clear space” Constant FilmTYpe = new GraphQLObjectType({ name: 'Film', description: 'A single film.', fields: () => ( { title: { type: GraphQLString, description: 'The title of this film.', }, episodeID: { type: GraphQLInt, description: 'The episode number of this film.', }, openingCrawl: { type: GraphQLString, description: ‘The opening paragraphs at the beginning of this film.', }, director: { type: GraphQLString, description: ‘The name of the director of this film.', }, @jwscott22
39. GraphiQL Docs Features 1. Inline descriptions 2. Autocomplete 3. Hover tool-tips 4. (⌥ + Space) 5. Introspection 6. Docs Explorer
40. Other GraphQL tools @jwscott22
41. Not very human…. @jwscott22 “…an unhealthy reliance on the self-documenting aspects of GraphQL …” - Carolyn Stransky
42. What do other tech writers say? @jwscott22 “… we thought that it was important to have educational stuff and hand-holding material to introduce people to GraphQL… …you don’t want to just assume that people know how to formulate queries and mutations…” - Andrew Johnston “Documenting API endpoints explains how individual tools work,
 
 explaining how to use those tools together is a whole other area of documentation effort. …” - Chris Ward
43. Documenting GraphQL @jwscott22 1. Generic docs: • On-boarding/hand-holding docs on basics. 2. API specific docs: • Provide query and mutation examples. • Supporting docs for specific use cases. 3. In the API itself: • Choose appropriate names for your fields/types. • Use good descriptions in the schema.
44. @jwscott22 The end? “I didn’t think it would end this way.” “End? No, the journey doesn’t end here.”
45. • “My Code is Self-documenting” - Eric Holcher http://ericholscher.com/blog/ 2017/jan/27/code-is-self-documenting/ • “Why you should document your self-documenting code - Oleksandr Kaleniuk - https://hackernoon.com/why-you-should-document-your-self- documenting-code-1105a8a6852e • Lessons from 4 Years of GraphQL (Lee Byron speaking at GraphQL Summit 2016) https://www.youtube.com/watch?v=zVNrqo9XGOs • “Does GraphQL reduce the need for documentation?” - Chris Ward @ChrisChinch https://blog.codeship.com/documenting-graphql/ • Documenting GraphQL at Shopify - Andrew Johnston @andrewjtech https:// www.youtube.com/watch?v=uuzsEfLaGnU&feature=youtu.be • Life is Hard and so is learning GraphQL - Carolyn Stransky @carolstran https://youtu.be/FsRSdGuj588 Resources & Further Reading @jwscott22
46. • “self-documenting code” definition PC Magazine: https:// www.pcmag.com/encyclopedia/term/51077/self-documenting-code • The latest GraphQL spec: https://facebook.github.io/graphql/ June2018/ • Interview with GraphQL co-creator Lee Byron: https://nordicapis.com/ interview-with-graphql-co-creator-lee-byron/ • Repo of public GraphQL API docs and tools: https://github.com/ Jwscott22/GraphQL-docs • An extensive list of public GraphQL APIs: https://github.com/APIs- guru/graphql-apis • Who’s Using GraphQL - https://graphql.org/users/ Other Resources
47. • Image:Pair-Program-Step-3-Version-2.jpg - © Creative Commons • Hitchhikers Guide to the Galaxy - © Touchstone Pictures • Gollum from the Two Towers (2002) - Warner Bros • Art of Programming - © Geek and Poke • Unicorn from Blade Runner (1982) - © Warner Bros • Screenshot of Lessons from 4 Years of GraphQL - Apollo GraphQL • Success Kid - Wikimedia Commons • Pokemon Group - © Pokemon Company International Inc. • Magnifying Glass - © KissPNG.com • Robot Emoji- © emojiisland.com Media Copyright