How to Write “Good” API Documentation

By Natalie Kerby in Developer Posted Apr 2, 2015

Ever feel like you spend a lot of time writing API documentation but users still have basic questions? Or maybe the number of questions deterred you from having motivation to write documentation? Never fear, you are not alone. I would sometimes spend hours working on documentation, whether it be documenting code or functionality, and I still received questions from end users.

Good API Documentation

After doing some research on API documentation methods and reading a variety of examples, I concluded that writing great documentation is not an easy task.

I came across these two statements and they really stood out to me:

“Users don’t want documentation, they want answers”

“Documentation isn’t read, it is referenced”

In my opinion, these powerful statements are significant because they are 100% correct. I have found that not many customers will sit down and read the entire owners manual for the new big screen TV they just purchased. I know I’d toss the owner’s manual aside with the thought “How different could this TV’s functionality really be from my previous TV?” and continue setup. I would only consult the owners manual if something went wrong or was not working as expected.

So Let’s Get to It:

The overall goal of documentation is to provide users with understandable, accurate information that is easily accessible.

These are some points I consider to help reach that goal and in order to write “Good” API documentation:
– Know your users.
– Understand what users want to accomplish.
– Keep it simple.
– Proof-read the documentation.

Know your users:

This might seem obvious, but involves more thought than you might realize. Think about how a conversation with a colleague is much different than a conversation with a child in terms of vocabulary, background knowledge assumptions, and guidance. For example, take a look at a children’s book and an adult’s mystery book. Notice that the two books are completely different in terms of detail, clues, and length? The children’s book will not only guide the child to each of the clues but will also bluntly point out each clue and how it contributes to the mystery. Whereas the adult’s novel will send the reader off on a journey but it is up to the reader to investigate and sift through all the information provided to try to solve the mystery before the end.

Having an understanding of who will be reading your documentation will help extraordinarily because it will help you focus on how much detail and guidance you need to give. The challenge isn’t over yet as you will need to decide how the information should be presented.

Understand what users want to accomplish:

Take a step back as the “expert of the product” and actually use your product as your users would. Allow enough time to get first-hand exposure to what users will see. This will help because now you can speak directly to what they will see, include screenshots or examples if need-be. It is safe to assume users will have no background knowledge of your application. So ask yourself “If I did not work on this product, would I know what to do? Do these error messages give the user enough information to know how to fix it if something goes wrong?” These are important things that contribute to the overall user experience. If you can give clear guidance through questionable areas, you have already helped the majority of your users.

Keep it simple:

You don’t want to overwhelm your users with a wall of text if you can help it. Some ways to help simplify is to play with words a little. A ten word sentence can sometimes be a five word sentence. To do this, write the sentence, then walk away, get a cup of coffee or something.

REST API Documentation

Then come back and ask yourself “What is the point of this statement?”. See if there is any way to remove some of the fluff. Doing this will help keep your documentation focused and allow users to get their answers more quickly.

Proof-read the documentation:

After you finish the documentation, ask a friend or two to proof-read your document because what makes sense to you will not always make sense to your neighbor. If possible, ask someone who is unfamiliar with the application. This will give you the best possible feedback because they are going to be most similar to your user in terms of application knowledge.

Things to Keep in Mind:

Now it is important to remember these four things about your documentation:
– It will not answer everyone’s questions.
– It will not make sense to everyone.
– It will help users use the application.
– It will help surface some more intelligent questions from users.
Everyone understands information differently and there will always be some quirky un-accounted-for bugs that users will find, which is 100% fine.

Final Thoughts:

As I mentioned earlier, documentation is not an easy task but if you give it some time and thought, it will go a long way to helping users understand and use your application. Lastly, remember to update your documentation as your application evolves. Happy Documenting!

Check out Cloud Elements' API documentation here. 

For guides, articles, infographics and webinars on API integration and manangement, check out our API Resource Center.

Visit Resource Center

References:
http://www.techscribe.co.uk/techw/good-documentation.htm
http://www.bluemangolearning.com/methodologies/software_documentation.html


bad_doc_youre-better-than-this-1.gifGet the State of API Integration Report