Have Amazon, Dropbox, Microsoft and Google got their information design wrong?

On an API documentation course we ran for a client yesterday, we showed a number of developer documentation websites, including ones from Amazon, Dropbox, Google and Microsoft. One common theme the delegates noticed was these sites contained a in-page table of contents, or a set of related links, on the right hand set of the screen. You will… Read more »

Documentation as an API – the docsbot

In a recent presentation, Twilio’s Jarod Reyes and Andrew Baker mentioned their plans to make Twilio’s developer documentation available as an API. They plan to start with an API for code samples, stored in a github repository. Making documentation available as an API means means users can create or remix their own versions of the documentation. For example, they could… Read more »

Research into how API documentation fails

There isn’t a great deal of research into API documentation, and the factors that make API content good or bad. Here’s some of the papers we’ve found so far: How API documentation fails. Research by Uddin and Robillard, McGill University, 2015. Creating and Evolving Developer Documentation: Understanding the Decisions of Open Source Contributors, Dagenais and Robillard, 2010…. Read more »

Microsoft publishes its REST API Design Guidelines

Microsoft has published  its REST API Design Guidelines to the API community. According to Gareth Jones, Principal API Architect, who announced its release: “The effort got started from hearing two key points of feedback from customers: It should be easier to get started with Microsoft APIs – Developers wanted to be able to run the curl tool… Read more »

MadWorld 2016 Conference Review – Day One

Last week, I spoke at, and attended, Madworld 2016, the conference hosted by MadCap Software for its users. It’s the most rewarding and enjoyable of all the conferences on technical communication that I attend. Here is a summary of what I saw and heard on the first day.