Developers are raving about how GraphQL is “self-documenting” and how it doesn’t need docs but I disagree. I want to debunk the self-documenting myth, talk about why naming is so important in GraphQL and explain why technical writers still have a key role to play in its documentation.

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 that 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
@jwscott22
iOS News Feed
iOS Messenger
Ads Manager
Facebook Lite
iPad Pages
Android Feed

16. Relay
GraphQL
@jwscott22
Open-sourcing of GraphQL

17. @jwscott22

18. So what is GraphQL?
• 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 actually 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. Introspection (⌥ + 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 work 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. @jwscott22
Questions?

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

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

48. • 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