Slides from the London Technical Evangelism meet up, where we were discussing different approaches to documenting API's to keep it simple for developers

1. Greetings from Mailjet
Developer Evangelist / Beard - /tsims@mailjet.com @4thfloor_monkey
Find the slides at : evangelistsbarcamp.herokuapp.com

3. Who are Mailjet?

4. The Rise and Rise of the API
That's why we're all here...?

5. We've got one too
It's the core of what we do
Everything is built on top of it.
We are drinking our own champagne!

6. Why is it so important?
It offers flexibility
It adds value to other companies products
Anybody integrated Skype with anything recently?

7. Developer Experience
First step... 'onboarding'

8. The ideal onboarding
experience should be:
Quick
Easy
Developers should see immediate value in the service

9. What helps?
Code libraries / plugins
Sample code or apps

10. What obstacles are there to
overcome?
Technical Debt from changing systems
Whether the API fits the product and has all the needed functionality

11. So Documentation is important

12. Difficult documentation can sink a good product
I'm sure you all have pet hates...
Good documentation and a good product make a GREAT product

13. Getting documentation right
Because everyone loves collaboration

14. What did we look at?

15. Jekyll

16. Built on Ruby
Support for templating, plugins and Ruby fun

17. Thoughts:
We liked it, it's pretty neat!
Doesn't have strong opinions on styling or implementation
This is both good and bad... like everything!

18. Swagger

19. Thoughts:
Allows you to directly test calls in the interface
Loads of community language integrations
Great for 'sandboxing', not as quick for documentation

20. Lots of information about the api calls, but a little hidden
So perhaps not for us.

21. Readme.io
DaaS - Documentation as a service?

22. Thoughts:
Looks nice
Aims to simplify and save you time
There are costs involved
Not quite as flexible as rolling your own

23. We went with Slate
More Ruby based fun!

24. It's great!
Inspired by the Stripe & Braintree documentation
Efficient layout
Quick to generate
Open Source
Highly customisable

25. It gives you:
An index of endpoints and space for explanations
Code required for the call
Response from the server
These are three things I definitely like to find in docs!

26. How does our documentation
work?
metadata.json
A nifty code generator
An introduction to JSON Schema
https://brandur.org/elegant-apis

27. {"IsReadOnly":false,
"Name":"listrecipient",
"Properties":[
{
"DataType":"TContact",
"DefaultValue":"",
"Description":"Referencetocontactwhichissuscribedtothecontactslist.",
"IsRequired":true,
"Name":"Contact",
"ReadOnly":true
},
{
"DataType":"Int64",
"DefaultValue":"",
"Description":"UniquenumericalIDforthisobject.",
"IsRequired":false,
"Name":"ID",
"ReadOnly":true
},

28. What are our aims?
Consistency and predictability
Speed of updating when the API updates
Ease of contributions

29. Disadvantages?
Documenting your documentation

30. Advantages
Time with the community!
Documentation less likely to stagnate
git diff is a wonderful thing
Fully integrated into Github workflow, with PR's and forks
Integrate update alerts on platforms like Slack to keep you on your
toes

31. Questions for the group:
What have you found to be your biggest documentation challenges?
Which changes have affected API adoption?

32. To the pub!