The following talk has been approved by the
NO STAR WARS VII SPOILERS
association of Star Wars fans.
AD API & DOC NERDS
AUDIENCES
DOCUMENT-API-TOPIA #APIDOCS
THIS TALK HAS BEEN RATED
Arnaud LAURET
@apihandyman
AXA Banque
Slide 2
Slide 2 text
A not so long time ago in an APIverse
not so far, far away....
I II III IV V VI VII
Slide 3
Slide 3 text
No content
Slide 4
Slide 4 text
No content
Slide 5
Slide 5 text
Documentation is
NOT ONLY end user’s one
Slide 6
Slide 6 text
Many different forms and audiences
Slide 7
Slide 7 text
Every instructions,
comments and
information needed to
build, maintain and
use an API and its
subsystems
Slide 8
Slide 8 text
No content
Slide 9
Slide 9 text
API and documentation
are more than related
Slide 10
Slide 10 text
Symbiotic relationship
Slide 11
Slide 11 text
Close and often long-term interaction
between 2 different species
Slide 12
Slide 12 text
Mutualism
Slide 13
Slide 13 text
Both individuals benefit
Slide 14
Slide 14 text
No content
Slide 15
Slide 15 text
Parasitism
Slide 16
Slide 16 text
One benefits, One is harmed
Slide 17
Slide 17 text
No content
Slide 18
Slide 18 text
Synnecrosis
Slide 19
Slide 19 text
Detrimental to both
Slide 20
Slide 20 text
No content
Slide 21
Slide 21 text
API & Documentation succeed together
or fall to the dark side
Slide 22
Slide 22 text
I II III IV V VI VII
TAKEAWAYS
Episode I DOCUMENTATION MATTERS
Slide 23
Slide 23 text
No content
Slide 24
Slide 24 text
Unread documentation
Slide 25
Slide 25 text
Right people write the right documentation
for the right audience and right context.
Slide 26
Slide 26 text
Creating documentation is a real job
Slide 27
Slide 27 text
Document only when needed
Slide 28
Slide 28 text
Adapted to the subject
Slide 29
Slide 29 text
Adapted to the audience
Slide 30
Slide 30 text
Adapted to the context
Slide 31
Slide 31 text
No content
Slide 32
Slide 32 text
Standardized
Slide 33
Slide 33 text
Standardized API and subsystems
Slide 34
Slide 34 text
Standardized documentation
Slide 35
Slide 35 text
No content
Slide 36
Slide 36 text
Micronized
Slide 37
Slide 37 text
Microservices
Slide 38
Slide 38 text
Microdocumentations
Slide 39
Slide 39 text
No content
Slide 40
Slide 40 text
Analyzed and Tracked
Slide 41
Slide 41 text
Consistent with dependancies
Slide 42
Slide 42 text
Consistent with subject
Slide 43
Slide 43 text
Usage
Slide 44
Slide 44 text
Referenced
Slide 45
Slide 45 text
I II III IV V VI VII
TAKEAWAYS
Episode I
Episode II
DOCUMENTATION MATTERS
FIGHT UNREAD DOCUMENTATION
Slide 46
Slide 46 text
No content
Slide 47
Slide 47 text
No content
Slide 48
Slide 48 text
Documentation as code
Slide 49
Slide 49 text
Structured text
Human and machine readable
Slide 50
Slide 50 text
Documentation Version Control System
Slide 51
Slide 51 text
No content
Slide 52
Slide 52 text
Documentation Package Manager
Slide 53
Slide 53 text
DPM search
Slide 54
Slide 54 text
DPM install api-guidelines --save-doc
Slide 55
Slide 55 text
DPM link my-api --save-impl
Slide 56
Slide 56 text
Consistency checked using DPM descriptor
Slide 57
Slide 57 text
Automatically updated
Slide 58
Slide 58 text
Documentation Factory
Slide 59
Slide 59 text
Integrated Documentation Environment
Slide 60
Slide 60 text
Documentation Continuous Delivery
Slide 61
Slide 61 text
I II III IV V VI VII
TAKEAWAYS
Episode I
Episode II
Episode III
DOCUMENTATION MATTERS
FIGHT UNREAD DOCUMENTATION
TREAT DOCUMENTATION AS CODE
Slide 62
Slide 62 text
No content
Slide 63
Slide 63 text
No content
Slide 64
Slide 64 text
Documentation as Code
Slide 65
Slide 65 text
Documentation as Data
Slide 66
Slide 66 text
Documentation as API
Slide 67
Slide 67 text
Documentation visualization
Slide 68
Slide 68 text
Interactive Documentation Visualization
Slide 69
Slide 69 text
I II III IV V VI VII
TAKEAWAYS
Episode I
Episode II
Episode III
Episode IV
DOCUMENTATION MATTERS
THINK ABOUT AN IDEAL WORLD
TREAT DOCUMENTATION AS CODE
USE DOCUMENTATION AS DATA
Slide 70
Slide 70 text
No content
Slide 71
Slide 71 text
Documentation is for people
Slide 72
Slide 72 text
No content
Slide 73
Slide 73 text
less than 2000 pieces?
Slide 74
Slide 74 text
more then 2000 thousand?
Slide 75
Slide 75 text
3349 pieces
Slide 76
Slide 76 text
An API descriptor is not
THE end user’s documentation
Slide 77
Slide 77 text
Story telling
Slide 78
Slide 78 text
Interactive Story telling
Slide 79
Slide 79 text
One size does not fit all
Slide 80
Slide 80 text
I II III IV V VI VII
TAKEAWAYS
Episode I
Episode II
Episode III
Episode IV
Episode V
DOCUMENTATION MATTERS
FIGHT UNREAD DOCUMENTATION
TREAT DOCUMENTATION AS CODE
USE DOCUMENTATION AS DATA
DOCUMENTATION IS FOR PEOPLE TOO
Slide 81
Slide 81 text
No content
Slide 82
Slide 82 text
No content
Slide 83
Slide 83 text
Hyperdocumentation
Slide 84
Slide 84 text
Hypermedia
Slide 85
Slide 85 text
Content negotiation
Slide 86
Slide 86 text
application/json+documentation
Slide 87
Slide 87 text
documentation/tutorial+video
Slide 88
Slide 88 text
Metadocumentation
Slide 89
Slide 89 text
I II III IV V VI VII
TAKEAWAYS
Episode I
Episode II
Episode III
Episode IV
Episode V
Episode VI
DOCUMENTATION MATTERS
FIGHT UNREAD DOCUMENTATION
TREAT DOCUMENTATION AS CODE
USE DOCUMENTATION AS DATA
DOCUMENTATION IS FOR PEOPLE TOO
PROVIDE META DOCUMENTATION
Slide 90
Slide 90 text
No content
Slide 91
Slide 91 text
I can’t believe it.
This is why you fail.
Slide 92
Slide 92 text
SO MANY SEEDS
Meta documentation
Text documentation
Visualizations
API descriptors and tools
Hypermedia and tools
Data and dependancies
CI and CD tools
Concepts
Documentation tools
...
APIS.JSON ...
MARKDOWN ASCIIDOC YAML ...
3DJS MERMAID UNITY ...
SWAGGER RAML BLUEPRINT ...
SIREN HAL HYDRA UBER …
NEO4J NPM PIP RUBYGEMS ...
JENKINS GO CD …
TDD BDD UML MICROSERVICES ...
ARDOQ CORILLA ...
...
Slide 93
Slide 93 text
I II III IV V VI VII
TAKEAWAYS
Episode I
Episode II
Episode III
Episode IV
Episode V
Episode VI
Episode VII
DOCUMENTATION MATTERS
FIGHT UNREAD DOCUMENTATION
TREAT DOCUMENTATION AS CODE
USE DOCUMENTATION AS DATA
DOCUMENTATION IS FOR PEOPLE TOO
PROVIDE META DOCUMENTATION
THIS IDEAL IS WITHIN REACH
Slide 94
Slide 94 text
VERY SPECIAL THX
@paulsbruce
@jkriggins
@kinlane
PAUL BRUCE
JENNIFER K. RIGGINS
KIN LANE
MAY THE DOCUMENTATION BE WITH YOUR API.
ALWAYS.
Join #APIDOCS
Created by
@apihandyman ARNAUD LAURET
and GEORGE LUCAS