I recently gave a talk at the API the Docs conference in London where I was finally able to share some valuable advice about GraphQL documentation. My talk followed my journey from first being told that GraphQL was self-documenting and didn’t need documentation, to speaking to GraphQL co-creator Lee Byron in my quest for answers and receiving the words of wisdom that I was able to share at the conference.
After initially being told by a developer that GraphQL wouldn’t need documentation, I was pretty sceptical, but as I starting researching I found numerous examples of developers advocating GraphQL’s self-documenting nature with someone even declaring that it didn’t need documentation.
Although the majority of people were fairly positive about the self-descriptive features, one tweet from a developer who was unhappy with the GraphQL documentation he had encountered made me realise I might be onto something.
🤖 What does “self-documenting” mean?
I explored what is meant by self-documenting – something written or structured in such a way that it can be understood without prior knowledge or documentation – and highlighted how the PC Magazine definition came with this caveat about subjectivity:
“It’s very subjective. However, what one programmer thinks is self- documenting may truly be indecipherable to another.”
I investigated the risks of subjectivity, how words like homographs such as “second”, “number” and “subject” can have multiple meanings and might be interpreted differently. I also shared different opinions on self-documenting code, how some people feel it is a myth and an excuse for developers to avoid writing documentation:
I also referred to a blog post by Write the Docs co-founder Eric Holscher who said self-documenting code was “one of the biggest documentation myths in the software industry”, adding that the self-documenting argument boils down to:
- I made something with a specific use.
- I gave it a name to represent that specific use.
- It doesn’t need documentation now because it’s obvious how it works.
Holscher argued that people who believe in a world of self-documenting code are actually making it more difficult for normal people to use their software.
🔬 How intuitive is GraphQL?
To test some of these self-documenting claims, I stripped out the introductory documentation from the Github GraphiQL explorer and asked six of my colleagues (members of QA, development and documentation) to try and retrieve my name, location and avatar URL with a GraphQL query from just my Github login name.
The results were pretty interesting with pretty much all of them struggling with the syntax and encountering fairly similar parsing errors. The amount of time it took them to formulate a query through trial and error proved to me that GraphQL isn’t actually that intuitive without some form of example query or hand-holding documentation to get you started.
The other common issue I have encountered with some GraphQL APIs was developers either failing to add descriptions or using ‘self-descriptive’ as a description for queries and fields that weren’t particularly descriptive. Some of these relied on assumed knowledge, expecting the end user to have a prior knowledge of the schema and the data it relates to.
After looking at the GraphQL spec, I found this line, which might explain why some developers are not including descriptions: “All GraphQL types, fields, arguments and other definitions which can be described should provide a description unless they are considered self descriptive.”
Whether they realise it or not, the issue is these people are unintentionally making it difficult for people to use their APIs. GraphQL co-creator Lee Byron spoke about the importance of naming at the GraphQL Summit in 2016:
“It’s really important not just to have names that are good but to have names that are self-documenting […] Naming things that adhere closely to what those things actually do is really important to make this experience actually work.”
🐴 Straight from the horse’s mouth
I thought this was pretty interesting but I still wanted a definitive answer about GraphQL documentation so I emailed Lee Byron, who also happens to be the editor of the GraphQL spec, asking him if he would answer some of my questions. To my surprise he agreed to an interview back in September. We spoke for about half an hour and he told me all about the history of GraphQL, his hopes for its development and we touched upon documentation. When I asked him about the importance of descriptions in GraphQL, he gave the following advice:
“APIs are a design problem, way more than they’re a technical problem and you know this better than anybody else if you’re working on documentation.
If there’s no documentation, it doesn’t matter how good the API is because so much about what makes an API work well is mapping well to your internal mental model for how something works and then helping explain those linkages and the details.
If you do that wrong, it doesn’t matter how good your API is, people aren’t going to be able to use it.”
“GraphQL doesn’t do that for you, it provides some clear space for you to do that.
There’s the types and the fields and introspection, you can add descriptions in places so it wants to help you but if you don’t put in the thought and you end up with a poorly designed API, that’s not necessarily GraphQL’s fault right?”
I asked Lee’s permission to use the video clip of him giving this advice during my talk as I knew it would resonate with other API documentarians and having one of the GraphQL co-creators validate what I’d set out to prove all along was a pretty awesome mic drop moment for me!
✍️ So how do we document GraphQL?
Lee Byron spoke about how GraphQL provides you with “clear space” for the documentation: the types, the fields, the descriptions and introspection. So by using self-descriptive names for the types and fields and by using good descriptions in your GraphQL schema, you make it a much more user-friendly experience for your end user. I have highlighted where descriptions appear in GraphiQL for the Star Wars API (SWAPI):
However, these descriptions will only get you so far because documentation generated dynamically from your schema is never going to be very human.
Former technical writer and developer Carolyn Stransky spoke about this issue and a number of other blockers she encountered while trying to learn GraphQL at the GraphQL Finland conference. These included “an unhealthy reliance on the self-documenting aspects of GraphQL”, unexplained jargon and assumed knowledge. She felt most of these issues could have been easily prevented if more care and consideration had gone into the documentation.
I wanted to see what other technical writers were saying about GraphQL documentation but given the technology is so new, my questions on the Write the Docs Slack channel and other forums went unanswered. However, I did find a couple of good resources.
Andrew Johnston, who works on the GraphQL documentation at Shopify, spoke about the importance of providing on-boarding or “hand-holding” documentation for people who are new to GraphQL and not just assuming your end users will know how to formulate queries and mutations.
Technical writer Chris Ward wrote a blog post about whether GraphQL reduces the need for documentation and concluded that while it “offers a lot of positives on the documentation front”, documentarians should treat it just like any other API. He wrote:
“Documenting API endpoints explains how individual tools work, explaining how to use those tools together is a whole other area of documentation effort. This means there is still a need for documentation efforts in on-boarding, getting started guides, tutorials, and conceptual documentation.”
So my conclusion was GraphQL can be self-documenting but only if you put in the effort to give your fields and your types self-descriptive names, if you add good descriptions and if you provide adequate supporting documentation, especially for people who are new to GraphQL. Ultimately I think technical writers have a pretty important role to play in documenting GraphQL and ensuring the experience works, to repeat Lee Byron’s advice – if your API doesn’t have any documentation then people aren’t going to be able to use it.