After spending time in API docs, I wanted to point out what makes a good and easy API document for a new programmer.
When working on my GitHub and Google Sheets I read through the API documentation and trying to find what I needed. While both documents were quite informative. Trying to understand all of it as new programmer was sort of a nightmare.
In terms of rank, I felt like Github was the easiest, while I felt like the Google Sheets was a bit more difficult maybe because I had to deal with concept of how to post to and row and column. I’m still struggling with this part of my project.
As I went off on a tangent, I started looking at other API documents and how they are designed and I made note of things I liked about the API documentation.
- Table of Contents Placement
One of the things I like is the Table of contents to be on the left of the API documentation. We generally read left to right, so from a design aspect I didn’t like the API documents that had their table of contents on the right. Cough. Github.
Twilio does a GREAT job at this. Many API documents are REALLY long. Like you’re scrolling forever and you could lose yourself in it. Sometimes lose your place. Twilio has a panel for the information you need and then code references on the right panel. It makes for a lot less scrolling and a great design choice