Last week I and my colleague Chris attended APIdays Mediterranea in Barcelona.
To kick things off we had a story from Mike Amundsen called From Stacia to Hyperion and Back Again: A Hypermedia Hero’s Tale. Our hero in the story leaves the town of Stacia and embarks on an adventure to find the magical city of Hyperion. We found a monkey, an owl and a door with a skeleton hanging off the door handle. Only very experienced speakers can deliver a made up ancient myth to ultimately remind us of the wonder of computing, hypermedia and how designers can’t ever really imagine how the things they design will end up being used.
As Mike was giving his talk then I found this Tweet:
Another highlight was a talk by PayMill Developer Evangelist Yann Irbah called Beyond Docs: Lessons learned rebuilding an API documentation. Keeping on top of documentation with a fast moving API is extremely difficult. It’s the task that nobody likes to do. We all know that familiar groan when you ask someone to write some docs.
When you are an API provider then documentation is just not negotiable. An API simply does not exist if you do not provide information about how to use it. Yann talked about how documentation is more than just product usage information. It’s marketing by technical people for technical people. Good documentation is also a trust builder. If developers see that your documentation is regularly updated then they know you can be trusted and you care. I believe it can be used as a design tool; when you are designing an API ask yourself ‘how would I document this?’, and if you find yourself struggling then perhaps you need to rethink your API.
There is a lot to consider when writing documentation for example:
- the Hello World example – How quickly can a new user make the first call to the API? This is often referred to as Time To First Call. If it takes a long time then developers will just go and find another solution to their problem.
- the API reference – detailed descriptions of each endpoint including code samples, descriptions of attributes and errors.
- the general overview – how do all the objects in your API fit together? What are these objects? What are the relationships with other objects?
- documentation tone – how to cater for experienced developers and the not so experienced?
Essentially though it has to be something that is easy for authors to do. This is why we picked Slate because of the fact it uses Markdown. We have Swagger for our interactive documentation where developers annotate their code as they are writing endpoints.
When it comes to documentation it will always come down to getting people to care enough about it to want to do it. I really don’t have an answer for that right now.
My final highlight was by Manfred Bortenschlager who gave a talk about running a successful API program — and he should know, being the API market development director for 3Scale. Manfred has redrawn the Business Model Canvas and created an API Model Canvas. Mehdi Medjaoui, founder of OAuth.io mentioned after this talk that each week his team would sit and iterate over their business model canvas to ensure that it was always up to date. I’m really keen to have a go at this and get one filled out for Mendeley. It will help us focus on our API offering and I’m hoping to use it as a communication tool so that everybody in our company understands the value we are offering with our API.
I really can’t recommend attending these conferences enough. The organisers do an amazing job to ensure that everybody feels welcome. Do yourself a favour and get yourself a ticket for one of the events.