Document-API-topia

 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

Ba9efb844dce84e8b0c7d0f98535895d?s=128

Arnaud Lauret API Handyman

December 08, 2015
Tweet

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
  3. None
  4. None
  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
  8. None
  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

  14. None
  15. Parasitism

  16. One benefits, One is harmed

  17. None
  18. Synnecrosis

  19. Detrimental to both

  20. None
  21. API & Documentation succeed together or fall to the dark

    side
  22. I II III IV V VI VII TAKEAWAYS Episode I

    DOCUMENTATION MATTERS
  23. None
  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

  31. None
  32. Standardized

  33. Standardized API and subsystems

  34. Standardized documentation

  35. None
  36. Micronized

  37. Microservices

  38. Microdocumentations

  39. None
  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
  46. None
  47. None
  48. Documentation as code

  49. Structured text Human and machine readable

  50. Documentation Version Control System

  51. None
  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
  62. None
  63. None
  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
  70. None
  71. Documentation is for people

  72. None
  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
  81. None
  82. None
  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
  90. None
  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