Documentation Continuous Delivery

A technical introduction to Documentation Continuous Delivery and how we can start to implement it with existing tools.

Transcript

1. Documentation Continuous Delivery A technical introduction Arnaud Lauret @apihandyman AXA Banque
2. @apihandyman bit.ly/DocApiTopia Prologue Previously in Document-API-topia
3. Chapter 1 Documentation Documentation disease
4. Let’s talk about documentation
5. Create Run Evolve Use
6. API & Documentation
7. API Dev Portal SDK End user’s documentation
8. Provider’s documentation API Subsystems Infrastructure Databases ... Dev Portal Source code Partners SDK Dependancies End user’s documentation
9. What’s the problem with doc, Doc?
10. Hard to create Disconnected Not adapted Not up to date
11. What’s the cure?
12. Chapter 2 Documentation Continuous Delivery The cure
13. Treat documentation as software
14. Integrate documentation within existing continous delivery system Code -> Build -> Test -> Deploy
15. Code = Create raw documentation
16. Build = Render documentation
17. Test and deploy as usual
18. Chapter 3 Raw documentation Documentation as Code Code as Documentation
19. Documentation Management Source Code Management
20. DOC TXT
21. Lightweight markup languages Markdown, GFM, ASCIIDoc, ...
22. Mermaid, PlantUML, yUML, ... sequenceDiagram A->> B: Query B->> C: Forward query Note right of C: Thinking… C->> B: Response B->> A: Forward response
23. API Definition Languages OAS (Swagger), RAML, Blueprint
24. @Documentation in Code (js|php|java|r)doc springfox, swagger-php
25. Source code Dependancies Behaviour driven development tests Infra as code
26. Chapter 4 Render documentation Documentation as Data
27. Simple rendering
28. Interactive rendering
29. Visualization
30. Documentation as Data
31. Epilogue Is it the end?
32. Pushing documentation as code concepts
33. Creating documentation for end users is a real job
34. Questions?
36. 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/