Mailjet recently release a new version of its API documentation, fully revisited. This talk is a return of experience on what we've learnt building it.

1. 1
Revamping our API documentation
Return of experience
#ParisAPI
22 October 2015

2. Our Agenda today
Let’s make it clear
Code generator
Be lazy!
51
Introduction
Who am I?
About Mailjet
Worldwide startup
2
API
Documentation
Why?
3
Behind
the scene
Our secret sauce
4
Finally
A small gift for you..
6
22

3. Arnaud Breton
Head of API and Developers
Relations
Who am I?
33
Formal front-end lead
developer @ Mention
CTO and co-founder of
UniShared / VideoNot.es
(Imagine K12 Alumni)
Endorphin addict
@arnaud_breton

4. API documentation for what ?
Why it matters
“We aim for the best Developer Experience"
Wrappers / Librairies
Everyone do not code in PHP
or Go..
44
Guides
Guide developers in their first
steps and in implementing
standard scenarios.
Reference
Full coverage of the nooks and
crannies of the API endpoints

5. API documentation
Before the revamp
Home made system
Making hard to:
• Maintain and focus on the content
• Publish the guides
• Accept contributions from community
• Integrate new languages
• Not mobile responsive
55
First version
• No search engine
• Sample codes featured in only 1 language (curl)
• Guides were a mix of reference and how-to
guides

6. 6
API Documentation
GOALS
Make an awesome first
impression to Developers
- Faster understanding
- Plug & play code samples
- Learning by coding
- Faster integration
- Step by step without clutter
P r o m o t i n g M a i l j e t
wrappers
- 6 languages and growing
- Easier to discover
Promoting demos to make
the doc interactive
Open for contributions

7. 7
TADA !

8. How did we get there ?
Take a step back
What developers really
care about?
Test the API
Think like a new user
88
Benchmark
Guides must be high
level, qualitative
documents
README.io
Stick to on premise
solution
Swagger
Too much endpoint /
reference driven

9. • Switching to Slate, open-source and actively maintained system. (TripIt)
• Inspired by the best (Stripe, Braintree)
• Focused on the content
• Facilitated navigation
• Publish the documentation source and accept contributions
• Responsive design
• Permalink to guide, facilitating sharing
• Integrated search features
• Code generator to automate hundreds code sample combinations
• Markdown, to standardise documentation formatting
API Guides - Behind the scene
99

10. 10
Sample code generator

11. 11
Sample code generator
Challenge
How to generate the same sample
codes in many languages, without
having to actually write them all
manually?
Don’t forget, we developers, are lazy…
well pragmatic !
Philosophy
Automate as much as possible,
manually do the rest (~10% were
manually written)

12. • Faster documentation of new API resources
• Faster maintenance of existing code samples
• Reduce errors
• Facilitating the learning by providing homogeneous code sample
• Very fast deployment of documentation for a new language/wrapper
Sample Code Generator - Benefits
1212

13. • Accelerated the implementation of new wrappers
• API and existing wrappers debugging
• Useful for other internal projects
• Even internally, speed up the API learning curve for Mailjetters
Sample Code Generator - Collateral Effects
1313

14. • Constantly improve the content based on feedback and document new features
• Improve the doc interactivity (console, rating, easter eggs, etc)
• Revamp our API Reference
• Making the release process reliable by automating code samples testing
• Depreciation and change management processes
• Publish internal focused API documentation
• Give back to Slate community
API Guides - What’s next ?
Because there is always room for improvements
1414

15. 15
Join us online @mailjetdev
Thanks!