1

Revamping our API documentationReturn of experience

#ParisAPI 22 October 2015

Our Agenda todayLet’s make it clear

Code generatorBe lazy!

51

IntroductionWho am I? About Mailjet

Worldwide startup

2

APIDocumentation

Why?

3

Behind the scene

Our secret sauce

4

FinallyA small gift for you..

6

22

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

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

API documentation Before the revamp

Home made systemMaking 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

API DocumentationGOALS

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

TADA !

How did we get there ?

Take a step back What developers really

care about?

Test the APIThink like a new user

88

BenchmarkGuides must be high

level, qualitative documents

README.ioStick to on premise

solution

SwaggerToo much endpoint /

reference driven

• 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

Sample code generator

11

Sample code generator

ChallengeHow 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 !

PhilosophyAutomate as much as possible, manually do the rest (~10% were manually written)

• 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

• 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

• 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

Join us online @mailjetdev

Thanks!