A talk focused on the trials and tribulations of learning GraphQL - and more consideration in our documentation can help. This post contains the video and a full transcript of the talk.

Presented on May 3, 2019 at the ReactJS Girls Conference.

🖥️ Slides
🔗 Resources

As Eve mentioned, my name is Carolyn and I'm a frontend developer based in Berlin, Germany. I'm working at a company called Blacklane and I'm also a Mozilla Tech Speaker. But before all of that, I worked as a technical writer so I've always been interested in how we learn new technologies - and particularly how documentation plays a role in that learning.

So first I want to tell you a bit about my story of learning GraphQL so you can kind of understand why I believe that it's difficult.

It all started when I went to a BerlinJS meetup and one of the speakers was a very nice human named Nikolas Burk. He talked about this thing called Graphcool, which is an open-source framework to develop and deploy serverless GraphQL backends. They've since pivoted to Prisma but this was... years ago. Now I had never heard of GraphQL at this point but I was in the market for a new technical writing role. And I kept thinking to myself like how cool it would be to have a say in how this new technology is documented.

I saw they had an open position, so I applied! And I landed an interview. As part of the interview process, Graphcool gave me one week to build a small application and write a tutorial for how to reproduce it. So I started thinking about what I could build. I already felt comfortable with React, plus I could use create-react-app to save time on development. I had to use Graphcool's GraphQL API because... it's their own product. And finally the Apollo client to connect it all. I'm not really sure if they told me to do it or if I thought that was the only way to work with GraphQL so that's what I did.

So yeah, I finished a few tutorials and had enough of an understanding to quick start and build something. I ended up building this cute little imageboard app and a tutorial to match - I know, it's a beautiful design, my talents are really wasted coding.

But for a variety of reasons, I didn't get the job. Of course, this wasn't the ideal outcome. But at the time I was kind of like... meh. I was pretty convinced that GraphQL was a phase and it would soon fade away like all of the other programming trends we see pop up on Twitter.

Shortly after, I started a new job at a different startup in Berlin that was building a content management system. And when we discussed the primary topics that our content would cover for the next year, three main things came up:
Static site generators, structured content and GraphQL. And my first reaction was like... what the hell. This is so niche, I was actually kind of mad about it - because I was like, why are we gonna spend a third of our energy on some sort of React tooling? Because that was honestly my perception of what it was.

But as I started researching again, I realized that my understanding of GraphQL was so shallow. Like yes, I had built a web app and yes, I had "made it GraphQL" - but I couldn't really explain any of the core concepts or even really what it was. Like I mentioned, I thought that it was some sort of random tooling like chalk or react-router.

So I dove back into learning, but it was difficult to know where to go because I couldn't take the same approach that I did with JavaScript because there's no 'vanilla' GraphQL. It's a spec, so there's not just one implementation of it.

I ended up asking around to my friends, what's the best way to learn GraphQL? And I basically received two types of answers. The first was to go to GraphiQL, which is an in-browser IDE for exploring GraphQL, and "try it out" - but like how do you do this? What data do you use? All of it was a mystery to me. Or the second option was I could work my way through the official GraphQL docs. Naturally, as a technical writer, I chose that option.

I ended up on this homepage and, my own story aside, this page already causes loads of confusion for many newcomers to GraphQL. Even just look at the term GraphQL. When I first heard of GraphQL, I figured it was like D3 or some sort of programming language that makes charts. Spoiler alert: It's not. But it's really not that ridiculous of a conclusion to come to if those are the only graphs that you know. The 'QL' also gets many people. It stands for 'query language' and people tend to associate that with databases because again... that's what they know.

Ok, back to the main page of the docs. So another primary point of confusion comes from that first sentence: "A query language for your API." This is confusing, and I would say slightly misleading, because one, it's not actually a language in the same way that we tend to think about programming languages. It's a specification. You can also query anything with it - like JSON files, CSS, etc. It's not just APIs, even if that's marketed as the primary use case.

Ok last thing, at least for now, but the GraphQL docs also have this 'Learn' page with this introduction to GraphQL and this giant sidebar of GraphQL concepts that you'll be guided through if you read the introduction and keep clicking next. Many people, myself included, take a lot of time to go through all of these because it's like 'oh well I mean, it's here and these are the official docs so it must be really important to know' - but it's not. The thing is that having a list like this is nice if you're stuck on a particular concept or, you know, you have this really specific thing in mind. But you don't need to learn all of this in order to be able to use GraphQL in a meaningful way.

So yeah, it doesn't make sense. But all rants aside, this issue is far bigger than the official documentation. No matter what source I went to there were a number of blockers that I kept running into while I was learning - like unexplained jargon or that it took me a really long time to realize that you can't use single quotes in GraphiQL. And it's important to note that all of these were preventable just by adding a bit more care and consideration into the documentation that we're creating.

Right now you might be thinking like... why should I care about this? And why are we gonna spend 20 minutes of a React conference talking about GraphQL documentation?

You're not wrong. But the reality is that this is important. Because, as I realized earlier on in my own story, GraphQL is more than just some kind of random trend. It's becoming more and more intertwined with the React community. And perhaps more importantly, the GraphQL ecosystem is at a really pivotal point right now. GraphQL is now stable and solidified enough to be used in production and to be used by developers across a large variety of skill sets.

Whether it's the latest GraphQL tooling or an open-source project that utilizes a GraphQL API, much of the documentation available doesn't allow for people just joining the industry or even just new to GraphQL to understand. Up until recently, GraphQL was seen as this more advanced concept but now it's being treated as just like a normal API. So anyone who encounters it needs to be able to understand it.

An excellent example of why this is important is Gatsby. So Marcy gave us a nice introduction to Gatsby and at the beginning of 2018, someone from their team mentioned that many of the issues that were being filed on GitHub were about GraphQL. People thought there was something wrong with Gatsby when really they just didn't understand how GraphQL works.

Another point is that GraphQL has evolved enough that, for the most part, the information is out there and available - it's just a matter of finding it because it's scattered throughout the internet or maybe our individual programming communities. So I would say it's up to us, any of us who know GraphQL well enough to document it, to be able to connect those dots and create more comprehensive materials for newcomers.

And because GraphQL is, I would argue, still fairly new and on the rise of being adopted - this is really the time that we can not only actually fix these problems but also see a real impact in the work that we're doing.

So I want to run through at least three of the problems that I encountered and consider ways that we could better enable our documentation for learning and comprehension. While I'll be talking about these in the context of GraphQL, most of what I'm saying is actually good practice for most technical writing. So maybe, hopefully, it's useful in some capacity to you.

First, I want to get this one out of the way because it's my personal pet peeve. There seems to be this idea out there that GraphQL both reduces the time you need to spend documenting your API and also the amount of documentation that your application actually needs. And that's just... not true. Yes, one of the reasons that GraphQL is so great is because there is this interactive piece to it. For example, if you're not sure what data is exposed by the API and you're on an interface like GraphiQL, the tool will autocomplete what's available for you. There are also these auto-generated explanatory docs based on the three main entry types into a GraphQL schema: Query, mutation and subscription.

But while these may ease our lives as developers, they aren't very human and they don't offer that guidance that we often expect, or maybe need, documentation to provide. There was this talk by Andrew Johnston at API the Docs where he explained that, "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... but without more detailed documentation that covers the conceptual materials, you're not going to get there."

There's one more quote that I find really fitting. Chris Ward, who's a technical writer based in Berlin, says that, "Documenting API endpoints explains how individual tools work, explaining how to use those tools together is a whole other area of documentation effort." He actually has an entire article on this topic, I've linked it... you can't see it but it's linked under here (all of my sources are). You can find them later I swear.

Anyway okay anyway so the basic idea is that you still need documentation efforts for things like onboarding guides or tutorials to explain how those general concepts tie into your specific use case.

Many products that rely on GraphQL as part of their core business have begun to do this and they do it pretty well. Since we were talking about Gatsby and their issue with GraphQL earlier, let's use them as an example. So now, if you go to their docs, they actually have an entire section
devoted to what GraphQL is, why they specifically chose it to query their data and how it works in the context of Gatsby - which gives you a good frame of reference when you're beginning to learn.

The next issue is another personal one because it took me an unreasonably long time to realize that GraphQL wasn't actually a JavaScript thing. To understand why GraphQL is so tightly woven with the JavaScript community, you need to understand a bit of its history. One of my favorite favorite descriptions of GraphQL came from S.C. Barrus where he described GraphQL as "another in a line of technologies that were emerging from the hipster catacombs at Facebook."

Because it was introduced by Facebook and particularly at a React conference, people naturally associated the two. As JavaScript developers, or at least people who are interested enough in JavaScript to be sitting here today,
this actually works to our advantage. It's great. By far, the JavaScript community has produced the most content, tutorials and how tos around GraphQL. Like I said, no complaints - it's pretty nice.

That being said, it's important to realize and recognize that GraphQL is actually framework agnostic and you can implement a GraphQL API using a bunch of different programming languages. This isn't even close to the full list. We need to give more visibility to this fact especially when we're creating introduction and onboarding materials. For example, I really like that on the 'Learn' tab of the GraphQL docs, it points you right away to a page with a list of libraries to help you implement GraphQL in many different languages. And that page itself provides a thorough list of server libraries, tools, services, etc. to help get you going.

The last major issue that I want to address right now is that the GraphQL community throws out a lot of assumed knowledge and a lot of really specific terminology and acronyms. This isn't necessarily done maliciously. What often happens is, in any type of technical writing or technical documentation, is that while you're writing it - you'll tend to write it as if you're talking to yourself. But the problem is that first-time users won't have that same frame of reference, so any unexplained term or skip step in the process can really destroy that learning journey for your user.

This is especially the case for anything GraphQL related. Projects using GraphQL need to explain it much more thoroughly, or at least link to other resources that can, because for many readers it'll be a completely new concept. And to be honest, I think it's going to be like this for at least the next couple of years.

What you need to remember is that no matter how intuitive you think your tool is or how advanced your users might be, everyone starts somewhere and everyone is a beginner at some point. One way to prevent this disconnect is to include any prerequisites for a tutorial or guide at the very beginning. This way, everyone starts off on equal footing and bonus points if you can link to any materials that might fill those knowledge gaps.

One resource you could link to is Apollo's GraphQL glossary. It's a comprehensive list of important GraphQL words and acronyms. Honestly, I think it's my favorite GraphQL learning resource that came out of 2018 - besides Eve's book, of course.

Or if you want to go a bit higher level, Facebook's Graph API documentation is another great resource to reference. They cover commonly misinterpreted definitions - like nodes, edges, fields - quite well and they give a good overview of thinking in terms of graphs.

In addition to these more fundamental issues, I want to go through a few quick tips about documenting GraphQL-related projects.

Be confident with your definitions. Even today, I still see new articles or tutorials being published where they define GraphQL using phrases like, "From my understanding..." or "I believe it's this way..." This brings no value because it really shatters your own credibility as the person who's writing it and it just further confuses people because then they're like 'Is this the real definition? I'm not sure.' The information is out there and available, you just need to find it and link to it.

Second - and Emma touched on this in her talk earlier - when you introduce a new tool or service, be sure to say what it is or at least provide a link to their docs and maybe explain why you chose it. Try to answer: What problem will this be solving and why do we need it.

And finally, be transparent when you know there's a specific use case that doesn't work. Just say something. You'll save people headaches in the long run and I really promise you it will not destroy your business.

Unfortunately, this talk isn't long enough to really cover the intricacies of documenting GraphQL concepts or how to better explain the core functionality - although I'm happy to talk about that later if you want. But if you are new to GraphQL, I do want to leave you with a few (free) resources available.

To start, HowToGraphQL.com offers a pretty solid overview of the concepts - plus it walks you through implementations and a bunch of different programming languages. The only prior knowledge necessary is a rough understanding of what an API is and understanding how client-server communication generally works.

HowToGraphQL, as it is today, is pretty backend heavy - there's literally only one frontend tutorial. So if you're a frontend developer, I'd recommend starting here to get the basics down and then moving to Peggy Rayzis's A Frontend Developer's Guide to GraphQL.

She did this as a talk at Fluent Conf last year but it's hidden behind like a Safari paywall - and now I feel bad that you can't see the links but I'll tweet the slides later so you can find the links. Fortunately, though she created GitHub repo that I would have said we're linked there. Perfect. Along with her slides and resources for the talk, she also wrote an accompanying article for CSS Tricks with the same title. Because she works at Apollo, she uses tools like the apollo-server and apollo-client in her examples - but don't let that intimidate you. The concepts are there, plus she provides example apps that are in React, Angular and Vue so you can reference and maybe compare between them.

If you are the type that does like to immediately go and try something out, I'd recommend experimenting with the GitHub GraphQL API. It's data that, if you're using GitHub regularly, you're probably already familiar with so it might be a bit easier to comprehend how to fetch the data and how that data is being structured.

There's also the Community Resources on the official GraphQL docs. It has a variety of resources from newsletters to podcasts that you can check out. It's not an exhaustive (or particularly diverse) list but it's a way to get going.

Finally, some shameless self-promotion, Sara Vieira and I had this idea of building this website that incorporates this idea of use cases and learning journeys into this kind of choose-your-own-adventure format. Admittedly, it's still super messy - see there's still like a lot of TODOs. You can file it under like things I'd love to give more time to but life gets in the way of open source. But please if you have any ideas or resource suggestions, check it out or send me a message.

There's just one last thing I want to say before I get off the stage. Has anyone here heard of monads? Ok, ok... I literally just did. So ok - I guess they're some sort of like functional programming thing - but they're infamously difficult to explain. In fact, this might be hard to read, but it says "Once you understand monads, you immediately become incapable of explaining them to anyone else."

And if you take away anything from this talk, please let it be this: Please don't let GraphQL become the new monads.

Did you find this helpful or useful? If yes, please consider buying me a coffee so I can continue to give talks like this ☕️