GraphQL: “If there’s no documentation, people aren’t going to be able to use it…”

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.

GRaphQL
An artist’s impression of me (left) at the start of my GraphQL journey…

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.” 

poor-software-quality-5454

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.

Screenshot 2018-11-05 at 16.00.01

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.”

Docs-first-class-feature-7856.png

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.

Lee-2

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):

GQL-Descriptions.png

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.

knowledge-is-power
Carolyn Stransky cited assumed knowledge and unexplained jargon as blockers she encountered while trying to learn GraphQL.

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.

Further reading: Here are my slides and my resources.

Advertisements

Is GraphQL really “self-documenting”?

If you Google for ‘API trends’ or ‘the future of APIs’ , one technology that crops up a lot is GraphQL. Developers rave about it being a more powerful and flexible alternative to REST. Not only that but if you’re a technical writer like me, claims that it is self-documenting are particularly interesting. So what is GraphQL and is it really as self-documenting as people say?

What is GraphQL?

GraphQL is an open source data query and manipulation language that was developed internally by Facebook for their mobile applications before being released publicly in 2015. Since then it has grown in popularity with some people claiming it might replace REST APIs in the future.

Like REST APIs, both operate over HTTP with requests being sent to retrieve or manipulate data. The key difference is with REST you might need to send requests to multiple endpoints to retrieve a particular set of data, with GraphQL there is only one endpoint so with a single request you can retrieve an object and all of its related objects.

For example, with this GraphQL schema and server wrapping the SWAPI (Star Wars API), you can retrieve multiple pieces of data using just one endpoint. In this case, finding out the species and home planet of Luke Skywalker by adding more fields to the endpoint:

Star-Wars-GraphQL

“The self-descriptive nature of GraphQL”

There seems to be plenty of love for GraphQL on Twitter with developers praising its speed, flexibility and introspective nature. The other key attribute that crops up a lot is “self-documenting” or “self-descriptive”:

One developer even went as far to say that GraphQL doesn’t require documentation at all. However, after playing around with GraphQL and experimenting with some public GraphQL examples out there, I’m not so sure I agree.

Naming matters

The key thing about GraphQL from a documentation perspective is the importance of naming. Lee Byron, one of developers behind GraphQL, spoke about this in his talk “Lessons from Four Years of GraphQL” at the GraphQL Summit in November 2016: “Naming things is super important in GraphQL APIs,” he said. “An important question to ask when designing APIs is ‘Would a new engineer understand this?'[… ] And that means no code names or server-side lingo.”

Lee-Byron
Lee Byron, one of the developers behind GraphQL, spoke about the importance of naming.

He continued: “Imagine that most of the engineers who are going to be using your API might not find it so easy to go and find out how that field maps to some underlying system. 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.”

“An important question to ask when designing APIs is ‘Would a new engineer understand this?’ […] Naming things that adhere closely to what those things actually do is really important to make this experience actually work.” – Lee Byron

Despite Byron’s warnings, fields with poor or no descriptions were a common issue in the different GraphQL APIs I looked at. In the example below, taken from the GraphiQL documentation explorer, I had no idea what the ‘section’ query field did or what data it sent back because it had no description:

Screen Shot 2018-07-25 at 18.44.37

Apart from the documentation explorer, another way to see what query and mutation fields are available is the auto-populating feature in GraphiQL. Hovering over the field or type reveals a description but this can be as useless as the description in the documentation explorer if all it says is ‘Self descriptive’, as this Twitter user found out:

Does GraphQL need documentation?

I agree that GraphQL is self-descriptive and if you’re familiar with the query language and the schema, its introspective nature means it is easy to refer to the description of a field or type to find out what it does. One of the other advantages of GraphQL is the API documentation is easy to keep accurate and up-to-date as the descriptions are pulled directly from the code. In version 0.7 or above of GraphQL, this is as simple as adding a comments directly above the type or field in the code:

Star-Wars

However, GraphQL is only “self-documenting” if the developer or a technical writer has given the fields adequately intuitive or self-descriptive names or has added decent descriptions for them in the schema code. If the names are obscure or the descriptions aren’t great then your GraphQL API is as useful as a chocolate teapot and there are already a few chocolate teapots out there from what I’ve seen. So I guess the good news for technical writers is that we still have a role to play in helping to document GraphQL, it isn’t a magical solution that renders us unnecessary just yet!

The Story behind Slate: An Interview with Robert Lord

Back in 2013, developer Robert Lord, then an 18-year-old intern at Tripit travel software company, was challenged to create an API documentation tool by his boss. It took him several weeks but the result was a beautiful, responsive API documentation generator called Slate. Five years later, it has grown into a popular open-source tool that is used by a number of global organisations and companies including NASA, IBM and Coinbase.

cover-image-for-above-the-entire-post
Robert Lord created Slate while interning at Tripit. Copyright© Concur Technologies,

Lord said the Slate project grew out of a set of requirements the Tripit engineering team had at the time. He said: “I was interning at TripIt and my boss pointed me towards some two-column documentation pages and said ‘We’d like a page like this for our new API.’ They also had the requirement that their technical writer could make changes, and I think they didn’t want to write raw HTML. I made a generator that ended up being pretty generic to any documentation, and convinced them to let me open source it.”

How to Use Slate

Slate is simple to use, you fork the Slate Github repository and create a clone. Next you customise the code to meet your requirements; adding a custom logo, fonts and any additional CSS styling in the source folders, before adding your API endpoints and their descriptions in Markdown.

screenshot-slate
Slate helps users to create beautiful, intelligent and responsive API documentation.

When you’re done, you start Slate and launch your API documentation site using Vagrant or create an image using Docker. The result is an attractive, responsive three-panelled API documentation site with code samples in multiple languages down one side and a smooth scrolling table of contents down the other. For more information on how to use Slate, follow the instructions in the Slate README.

Slate in the Wild

Today more than 90 people have contributed to Slate on Github, it has been forked more than 13,000 times and has been given more than 23,000 stars. Some of the organisations and companies listed as users include NASA, IBM, Sony, Monzo, Skyscanner and Coinbase. There is a list of more than 90 companies that have used it on the Slate in the Wild sub-page of the repository.

This slideshow requires JavaScript.

Lord admits he still finds it “pretty surreal” that such large companies have adopted what he labels the “buggy project” he created as a teenager. “I really did not expect anybody else to see it or care about it,” he said. “Slate never really had a big rush of new users all at once, the growth in stars has been more or less linear over the years. No hockey sticks here. So there was never a single moment where suddenly a bunch of people were using it, it was a very slow process of discovering one company at a time.”

Life after Slate

Interestingly, a year after working at Tripit, Lord interned at Stripe, one of the leading API-first companies whose own API documentation inspired him when creating Slate. Stripe realised the value of their product hinged on people being able to read and digest their APIs. They invested a lot of time and effort in developing their own in-house API documentation tool and set the bar for the rest of the industry with the two-panelled design that has inspired so many other API tools.

Lord had plans to develop further API tools but decided to focus on other things. “Initially had some plans for similar tools,” he said. “But I think I realized I’m still early in my career, and would rather branch out and work on a variety of projects instead of focusing in on just one area.” Despite moving onto other projects and being fairly modest about the success of Slate, it’s an impressive piece of work for the young developer to put on his resumé. Indeed, one of the main reasons he asked Tripit to allow him to open source the project was so he could show future employers his work. “I mostly convinced them to open source it just so I could point future employers to this chunk of code I wrote,” he said. One company clearly took notice, Lord starts work on Fuschia at Google in a few of weeks time.

Help Review – Mozilla Firefox

I stumbled across Mozilla Firefox’s help system last week and was interested to find most of the articles were largely written by volunteers. I hadn’t come across this kind of model for documentation before so it raised some interesting questions. For starters, can a group of volunteer technical writers collaborate to produce an effective help system?

2016-05-20 11_32_36-Mozilla Support

Mozilla released Firefox as an open-source web browser back in 2002 and as such the source code is open to anyone. As a non-profit organisation, Mozilla also relied heavily on the code, along with the support and documentation being largely maintained by volunteers. Although the company now has a large workforce of paid employees, an army of volunteers also still contribute to roughly 40% of its work, which includes not only the documentation but also coding tweaks (around 24% of all source code changes) and even the Firefox logo design. The help system was created through the SUMO technical writing program, which invited participants (a mixture of college students and technical writing professionals) to take part in each release cycle in order to produce the documentation. Although the program is not currently active, the participants and other volunteers still seem to be actively involved in maintaining the existing help articles.

Firefox-3

First Impressions

Visually, I think the design and layout of the Mozilla Support homepage is really appealing, with all of the individual products and their logos mapped out in different sections. It just looks cool. The simple grey background, contrasting with the colourful designs of the Mozilla product icons and clearly marked out sections make it very easy to navigate. It was interesting to discover that some of the legacy of Mozilla’s design is down to an interface designer called Steven Garrity wrote an article listing everything that was wrong with Mozilla’s visual identity back in 2003 and was subsequently invited to their head office and asked to head up their new visual identity team which led a re-brand in 2004 when the now well-known Firefox logo, designed by Jon Hicks, was introduced.

2016-05-24 12_55_59-Start

The help is broken down into nine help topics, with multiple articles under each topic. The documentation itself is clearly laid out, although the screenshots are sometimes different sizes and formats (some fade into background, some do not etc.) and it is easy to spot where different technical writers have worked on the same article and used different styles to highlight sections of a screenshot. In the example below, you can see three different contributors’ work, with one opting for a crimson red rectangle to highlight ‘Desktop’, another using a orange-red circle and the third person using a brighter scarlet red oval:

Inconsistent

Each page does actually list the authors of each article so it is possible to see how many people have contributed to each article. This particular article had eight contributors but other have even more, and unfortunately it shows:

2016-05-31 12_31_59-How do I tell if my connection to a website is secure_ _ Firefox Help

In this article, which had 22 contributors, there were little issues like the screenshots being slightly different sizes. While it’s not the end of the world, the different styles of writing and formatting are pretty noticeable, even for someone without mild OCD, and it can look a bit messy and unprofessional. I guess it’s the kind of thing that’s forgivable when you’re using a free open-source browser but it could be easily remedied if Mozilla implemented a style guide for all contributing technical authors to ensure there is more uniformity with terminology, screenshots and how things are highlighted. Alternatively an editor could go through and make edits to clean things up where necessary.

Features

One thing I was really pleased to see in the help was the occasional gif clip and a good number of tutorial videos which ensure the content is dynamic and semi-interactive for its readers. The videos, which have been produced by Mozilla senior UX designer Michael Verdi, are short and well edited so they are very watchable. He has a personal, informal style and friendly tone which is more engaging than a robotic Siri/Cortana-style  narration.

At the top of each article, there is also a drop-down menu on the left-hand side which has some pretty useful features such as a link to any discussion items on the article’s topic, multiple language translations of the article, showing what other articles are linked to the article you are reading and seeing the history of who contributed and edited the article.

2016-05-27 11_44_48-Photos

In terms of help and support, it has three main branches: Twitter, a support forum and help articles. Again, this is a great way for Mozilla to keep all of their bases covered. The other great thing people volunteer to assist with all three of those branches as well, with volunteer contributors on Twitter, volunteers answering questions on the support form and volunteers writing the help articles themselves. These volunteers are prompted to help by various Volunteer for Mozilla Support buttons, as shown in the screenshot  below:

2016-05-26 14_34_31-Start

There is constant encouragement to get involved in things like the “Army of Awesome” (their Twitter helpers) and statistics about how help matters. For example, “1 Tweet can save 1 day” and “1 article can be viewed by 400 million users”. It just has a really positive, pro-active community feel about it.

Another common theme is the carton Firefox character, who is like a superhero-type figure, which appeals to everyone’s inner geek. It’s another simple but effective way to make  the support pages fun and engaging.

This slideshow requires JavaScript.

Conclusion

I am really impressed with the content and support that is being produced by Mozilla, especially given the high percentage of work being done voluntarily. On top of the written content, they are also managing to offer video tutorial content and a Twitter help account which are further supported by a support forum. It would be useful to have a style guide or some kind of lead technical author/editor to iron out any issues with uniformity but overall I think Firefox’s support pages prove that open source projects can be reasonably well-documented through crowd-sourcing volunteer technical writers. I’m not sure this model of documentation would work for everyone but I think Mozilla have proved that volunteers can collaborate to produce an extensive help system, this clearly isn’t just a big work experience project.