Introducing Stoplight Platform, built from the ground up to work with your Git repos and workflows. Read the announcement
Design Quality APIs 10x Faster
In the fall of 2016, my teammate and I were tasked with the mission of improving my former company’s documentation and content. We spent a year working on all kinds of documentation — API references, guides, tutorials, and blog posts. I had been writing documentation off and on over the previous 5 years, but I wasn’t formally trained in technical writing. I was by no means inexperienced though, due to working on API documentation for projects and a startup and teaching Python Flask workshops towards the end of my computer science degree. This was the first time I had ever been able to focus on documentation, which allowed me to pursue my passion for helping people of all skill levels through technical documentation.
In that year, I learned a lot from the Write the Docs community, other API providers, and my own trials and errors. Last year, I spoke about it in a talk, “Things I Wish People Told Me About Writing Docs,” at the API Strategy and Practice Conference in Portland, OR. This multipart series is a survey of what I learned.
“Nation Shudders At Large Block Of Uninterrupted Text,” photo from The Onion
Do you know that feeling when The Onion is eerily right? This is one of those times. People might not be physically shuddering at your docs, but there’s a good chance they are doing it mentally. I struggled with the idea that people aren’t going to read what I write, unless I present it in the most easily digestible way. Heck, this could even happen for this blog post. (Note to self: Remind myself why I even write. 🤔)
In an eye-tracking study from the Neilson Norman Group in 2006, 232 users looked at thousands of Web pages. What they found was that users generally look at web pages in an F-pattern:
Heatmaps from Nielsen Norman Group
The study also found some alternative scanning patterns such as layer-cake pattern, spotted pattern, marking pattern, bypassing pattern, and commitment pattern. I highly recommend reviewing the rest of the report.
It’s important to note that F-pattern is negative for users, but good content design can help prevent F-shape scanning.
I learned some of these tips from Kevin Burke’s talk, “How to Write Documentation for Users that Don’t Read.” Kevin maintained Twilio’s docs from 2011 to 2014.
Moreover, there’s the usability of paragraphs. Similar to The Onion piece, when you read a paragraph many times over you gloss over the whole thing. So then why do we write so many paragraphs in docs? Let’s do an experiment from the Keen IO docs:
Quickly read this:
Event collections can have almost any name, but there are a few rules to follow: The name must be 64 characters or less. It must contain only Ascii characters. It cannot be a null value.
Now quickly read this:
Event collections can have almost any name, but there are a few rules to follow:
Both of these contain the exact same content. It’s not rocket science that the second one helps you comprehend the information better and in less time. We have to remember that some paragraphs can benefit from being broken up into bullets. If your paragraph contains a list of any kind, turn it into a bulleted list.
I’ll talk more documentation design and navigation in a later part of this series.
What’s API documentation without code, right? Code samples are all over many of our docs, and our users actually read them. However, the problem is, they don’t always read the stuff around them unless it jumps out at them.
The context in the code sample is important for developer success. Developers are quick to copy and paste. Here’s an example with the Keen IO API:
A developer quickly copies and pastes this code. And…
First, how do they even run this file? Probably node file_name.js but it wasn’t in the code. This could have been put in a comment at the top.
Okay, so they run it and… ReferenceError: Keen is not defined. ☹️ A Keen client was never instantiated, there’s no import or require statement at the top, and it only works if they npm installed the library.
They get those fixed and run it once more… guess what?! Another error! ☹️your_project_id and your_write_key were never stored anywhere.
These are all things that could be made more evident in the code.
Here’s an example from the Twilio docs that gives good context to the end user:
Photo from the Twilio Node Helper Library
It makes it very clear how you should install the library, include it in your code, and then what needs to be replaced in the sample code to run the sample.
Since we have lots of code samples in docs, successful copying and pasting becomes pretty key. Here’s are two example of where that breaks down:
# Copy and paste the following command $ gem install rails
It seems pretty harmless, right? Think again, what happens when you go copy and paste that in your command line? You will most likely get:
bash: command not found: $
It’s a common mistake. Either, you want your command to appear like it is in a command line environment or you accidentally copied it over yourself. I would recommend just leaving off the $. You can also find a way to make it not copy and pastable because the error will happen to your users and it will be annoying.
Here’s a more recent example: Have you checked how easy it is to select the code the user needs to copy?
Kelsey Hightower struggled to copy this code sample off of StackOverflow in a Google Cloud Next demo.
Did he do this intentionally? The world will never know. However, it represents the struggle of coders to copy large blocks of text on some documentation sites. Make sure the UI of your site makes it easy to copy large blocks of text. You can even break up those blocks to explain them in chunks making them more accessible to copy and understand.
I hope some of these tips help you the next time you are writing documentation. I’d love to hear what tips you’ve learned over the years that were helpful to you in the comments below. Update: Check out Part Two of the series!