×
Copy
Open
Link
Embed
Share
Beginning
This slide
Copy link URL
Copy link URL
Copy iframe embed code
Copy iframe embed code
Copy javascript embed code
Copy javascript embed code
Share
Tweet
Share
Tweet
Slide 1
Slide 1 text
Documentation Continuous Delivery A technical introduction Arnaud Lauret @apihandyman AXA Banque
Slide 2
Slide 2 text
@apihandyman bit.ly/DocApiTopia Prologue Previously in Document-API-topia
Slide 3
Slide 3 text
Chapter 1 Documentation Documentation disease
Slide 4
Slide 4 text
Let’s talk about documentation
Slide 5
Slide 5 text
Create Run Evolve Use
Slide 6
Slide 6 text
API & Documentation
Slide 7
Slide 7 text
API Dev Portal SDK End user’s documentation
Slide 8
Slide 8 text
Provider’s documentation API Subsystems Infrastructure Databases ... Dev Portal Source code Partners SDK Dependancies End user’s documentation
Slide 9
Slide 9 text
What’s the problem with doc, Doc?
Slide 10
Slide 10 text
Hard to create Disconnected Not adapted Not up to date
Slide 11
Slide 11 text
What’s the cure?
Slide 12
Slide 12 text
Chapter 2 Documentation Continuous Delivery The cure
Slide 13
Slide 13 text
Treat documentation as software
Slide 14
Slide 14 text
Integrate documentation within existing continous delivery system Code -> Build -> Test -> Deploy
Slide 15
Slide 15 text
Code = Create raw documentation
Slide 16
Slide 16 text
Build = Render documentation
Slide 17
Slide 17 text
Test and deploy as usual
Slide 18
Slide 18 text
Chapter 3 Raw documentation Documentation as Code Code as Documentation
Slide 19
Slide 19 text
Documentation Management Source Code Management
Slide 20
Slide 20 text
DOC TXT
Slide 21
Slide 21 text
Lightweight markup languages Markdown, GFM, ASCIIDoc, ...
Slide 22
Slide 22 text
Mermaid, PlantUML, yUML, ... sequenceDiagram A->> B: Query B->> C: Forward query Note right of C: Thinking… C->> B: Response B->> A: Forward response
Slide 23
Slide 23 text
API Definition Languages OAS (Swagger), RAML, Blueprint
Slide 24
Slide 24 text
@Documentation in Code (js|php|java|r)doc springfox, swagger-php
Slide 25
Slide 25 text
Source code Dependancies Behaviour driven development tests Infra as code
Slide 26
Slide 26 text
Chapter 4 Render documentation Documentation as Data
Slide 27
Slide 27 text
Simple rendering
Slide 28
Slide 28 text
Interactive rendering
Slide 29
Slide 29 text
Visualization
Slide 30
Slide 30 text
Documentation as Data
Slide 31
Slide 31 text
Epilogue Is it the end?
Slide 32
Slide 32 text
Pushing documentation as code concepts
Slide 33
Slide 33 text
Creating documentation for end users is a real job
Slide 34
Slide 34 text
Questions?
Slide 35
Slide 35 text
No content
Slide 36
Slide 36 text
Sick: https://www.flickr.com/photos/zyphichore/513800589/ Iceberg schematic: https://commons.wikimedia.org/wiki/File:Iceberg.svg Old books: https://commons.wikimedia.org/wiki/File:Old_book_bindings.jpg Doc Toy: https://www.flickr.com/photos/jdhancock/6227478999 Chemin de la folie: https://www.flickr.com/photos/enthuan/8449075823/ Turkish Cough Sirup: https://www.flickr. com/photos/boston_public_library/8557184003/ The Cure: https://www.flickr.com/photos/c32/8651504797/ Code:https://www.flickr.com/photos/brimley/455502609/ Build: https://www.flickr.com/photos/jdhancock/4378302122/ Test: https://www.flickr.com/photos/kwl/4809326028/ Raw documentation: https://www.flickr.com/photos/actualitte/9730999371/ Render documentation: https://commons.wikimedia.org/wiki/File:Star-LC-10- printer-01.jpg The end is near: https://www.flickr.com/photos/thomashawk/3012839072/ Endless road: https://www.flickr.com/photos/septim/11498052914/ Questions? https://www.flickr.com/photos/calavera/65098350/ Thank you: https://www.flickr.com/photos/nateone/3768979925/