Is GraphQL really self-documenting? James Scott Technical Writer at Moogsoft @jwscott22

@jwscott22

“A common mistake people make when trying to design something completely foolproof is to underestimate the ingenuity of complete fools.” - Douglas Adams @jwscott22

1. What is the problem? 
 2. What is GraphQL?
 3. What is the answer? Agenda @jwscott22

@jwscott22

What does “self-documenting” mean? Written and structured in such a way it can be understood without documentation or prior-knowledge. @jwscott22

Subjectivity with images @jwscott22

@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

@jwscott22 “Self-documenting code is a unicorn”

@jwscott22 Others have said similar…

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…

1. What is the problem? 
 2. What is GraphQL?
 3. What is the answer? Agenda @jwscott22

“…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

Founders of GraphQL Lee Byron Nick Schrock Dan Schafer Mobile app dev team lead Creator of SuperGraph Facebook News Feed engineer

GraphQL at Facebook iOS News Feed iOS Messenger Ads Manager Facebook Lite iPad Pages Android Feed @jwscott22

Relay GraphQL @jwscott22 Open-sourcing of GraphQL

@jwscott22

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

Thinking in Graphs @jwscott22 Graph theory!?

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

What does GraphQL look like? @jwscott22 { hero { name } } { "data" : { "hero" : { "name" : "Frodo" } } }

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" } ] } } }

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", } } ]

Query using arguments @jwscott22 { character(id:"6") { name height age } } { "data" : { "character" : { "name" : "Aragorn" "height" : 1.98 "age" : 210 } }

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" } ] } } }

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!

@jwscott22

@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 } } }

Scenario 1: Assumed Knowledge! @jwscott22

@jwscott22 Scenario 2: ‘Self descriptive’?

1. What is the problem? 
 2. What is GraphQL?
 3. What is the answer? Agenda @jwscott22

“Naming is Super Important…” @jwscott22 “Would a new engineer understand this?”

@jwscott22 “Naming things that adhere closely to what those things do is really important to make this experience work…”

What does the spec say? @jwscott22

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

@jwscott22 Advice from the co-creator

- 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

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

GraphiQL Docs Features 1. Inline descriptions 2. Autocomplete 3. Hover tool-tips 4. (⌥ + Space) 5. Introspection 6. Docs Explorer

Other GraphQL tools @jwscott22

Not very human…. @jwscott22 “…an unhealthy reliance on the self-documenting aspects of GraphQL …” - Carolyn Stransky

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

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.

@jwscott22 The end? “I didn’t think it would end this way.” “End? No, the journey doesn’t end here.”

• “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

• “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

• 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