Document-API-topia

Documentation matters for API. We need an ideal world where documentation and API live in perfect harmony.
Talk given at API Days Paris 2015
Video: http://bit.ly/docutopiavid

Transcript

1. 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
2. A not so long time ago in an APIverse not so far, far away.... I II III IV V VI VII
5. Documentation is NOT ONLY end user’s one
6. Many different forms and audiences
7. Every instructions, comments and information needed to build, maintain and use an API and its subsystems
9. API and documentation are more than related
10. Symbiotic relationship
11. Close and often long-term interaction between 2 different species
12. Mutualism
13. Both individuals benefit
15. Parasitism
16. One benefits, One is harmed
18. Synnecrosis
19. Detrimental to both
21. API & Documentation succeed together or fall to the dark side
22. I II III IV V VI VII TAKEAWAYS Episode I DOCUMENTATION MATTERS
24. Unread documentation
25. Right people write the right documentation for the right audience and right context.
26. Creating documentation is a real job
27. Document only when needed
28. Adapted to the subject
29. Adapted to the audience
30. Adapted to the context
32. Standardized
33. Standardized API and subsystems
34. Standardized documentation
36. Micronized
37. Microservices
38. Microdocumentations
40. Analyzed and Tracked
41. Consistent with dependancies
42. Consistent with subject
43. Usage
44. Referenced
45. I II III IV V VI VII TAKEAWAYS Episode I Episode II DOCUMENTATION MATTERS FIGHT UNREAD DOCUMENTATION
48. Documentation as code
49. Structured text Human and machine readable
50. Documentation Version Control System
52. Documentation Package Manager
53. DPM search
54. DPM install api-guidelines --save-doc
55. DPM link my-api --save-impl
56. Consistency checked using DPM descriptor
57. Automatically updated
58. Documentation Factory
59. Integrated Documentation Environment
60. Documentation Continuous Delivery
61. I II III IV V VI VII TAKEAWAYS Episode I Episode II Episode III DOCUMENTATION MATTERS FIGHT UNREAD DOCUMENTATION TREAT DOCUMENTATION AS CODE
64. Documentation as Code
65. Documentation as Data
66. Documentation as API
67. Documentation visualization
68. Interactive Documentation Visualization
69. 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
71. Documentation is for people
73. less than 2000 pieces?
74. more then 2000 thousand?
75. 3349 pieces
76. An API descriptor is not THE end user’s documentation
77. Story telling
78. Interactive Story telling
79. One size does not fit all
80. 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
83. Hyperdocumentation
84. Hypermedia
85. Content negotiation
86. application/json+documentation
87. documentation/tutorial+video
88. Metadocumentation
89. 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
91. I can’t believe it. This is why you fail.
92. 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 ... ...
93. 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
94. 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