Successfully reported this slideshow.
Your SlideShare is downloading. ×

Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015

Ad

Living
Documentation!
Jumpstart Workshop
cyrille martraire!
@cyriux

Ad

What do you expect?

Ad

And could improve
your code too?

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Check these out next

1 of 132 Ad
1 of 132 Ad
Advertisement

More Related Content

More from Mozaic Works (20)

Advertisement

Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015

  1. 1. Living Documentation! Jumpstart Workshop cyrille martraire! @cyriux
  2. 2. What do you expect?
  3. 3. And could improve your code too?
  4. 4. a source of frustration
  5. 5. not enough outdated CONSUMING DOC
  6. 6. boring task prefer coding PRODUCING DOC
  7. 7. we can do better…
  8. 8. much better Good Documentation also leads to better Design
  9. 9. Workshop
  10. 10. An existing Java project (from the USB drive) ! ☞ Explore, Change, Learn
  11. 11. Passionate developer PARIS Since 1999 ! @cyriux Cyrille Martraire
  12. 12. Paris Software Craftsmanship Community http://www.meetup.com/paris-software-craftsmanship/
  13. 13. TDD BDD DDD Legacy
  14. 14. Documentation
  15. 15. Documentation (sorry)
  16. 16. USING MS OFFICE
  17. 17. *NOT* CODING
  18. 18. We love executable stuff
  19. 19. Documentation, usually.
  20. 20. Obsolete & Misleading
  21. 21. Documentation Sucks
  22. 22. I don’t want to maintain documentation !
  23. 23. If we adopt a new mindset
  24. 24. What is documentation? Question:
  25. 25. What is documentation?
  26. 26. What is documentation?the purpose of
  27. 27. Passing Knowledge to other people Transmission
  28. 28. Passing Knowledge to other people Making Accessible
  29. 29. Passing Knowledge for the future Memory
  30. 30. Passing Knowledge for the future Compliance
  31. 31. KNOWLEDGE KNOWLEDGE KNOWLEDGE KNOWLEDGE
  32. 32. DOCUMENTATION NEEDED Long-run Critical Large Audience
  33. 33. DOCUMENTATION NEEDED No Waste
  34. 34. DOCUMENTATION Because we can often do better than documentation NO
  35. 35. MOST KNOWLEDGE IS ALREADY THERE Where? Obfuscated Non-Accessible Fragmented
  36. 36. DOCUMENTATION Capitalize on the knowledge that’s already there + a little bit more NO
  37. 37. CONVERSATIONS OVER DOCUMENTATION
  38. 38. ! Working Collectively
  39. 39. Workshop Now!
  40. 40. EVERGREEN DOCUMENT 1
  41. 41. README.md What’s wrong?
  42. 42. *Shamelessly stolen from the nicely presented competitor Fleetio Fleet Management solution* [Fleetio](https://www.fleetio.com/fuel-cards) ! # Project Phenix (Fuel Card Integration) ! Project Manager: Andrea Willeave ! ## Syncs daily Transaction data from the pump is automatically sent to Fleetio. No more manual entry of fuel receipts or downloading and importing fuel transactions across systems. ! ## Fuel Card Transaction Monitoring Transaction data from the pump are verified automatically against various rules to detect potential frauds: gas leakage, transactions too far from the vehicle etc. ! *The class responsible for that is called FuelCardMonitoring. Anomalies are detected if the vehicle is further than 300m away from the gas station, of if the transaction quantity exceeds the vehicle tank size by more than 5%* ! ## Odometer readings When drivers enter mileage at the pump, Fleetio uses that information to trigger service reminders. This time-saving approach helps you stay on top of maintenance and keeps your vehicles performing their best. ! *This module is to be launched in February 2015. Please contact us for more details.* ! ## Smart fuel management MPG and cost-per-mile are automatically calculated. Analyze your fuel spend from all angles - by vehicle, location, vehicle type, time frame. ! ! ## Customers Words
  43. 43. Stable knowledge? Easy.
  44. 44. *Shamelessly stolen from the nicely presented competitor Fleetio Fleet Management solution* [Fleetio](https://www.fleetio.com/fuel-cards) ! # Project Phenix (Fuel Card Integration) ! Project Manager: Andrea Willeave ! ## Syncs daily Transaction data from the pump is automatically sent to Fleetio. No more manual entry of fuel receipts or downloading and importing fuel transactions across systems. ! ## Fuel Card Transaction Monitoring Transaction data from the pump are verified automatically against various rules to detect potential frauds: gas leakage, transactions too far from the vehicle etc. ! *The class responsible for that is called FuelCardMonitoring. Anomalies are detected if the vehicle is further than 300m away from the gas station, of if the transaction quantity exceeds the vehicle tank size by more than 5%* ! ## Odometer readings When drivers enter mileage at the pump, Fleetio uses that information to trigger service reminders. This time-saving approach helps you stay on top of maintenance and keeps your vehicles performing their best. ! *This module is to be launched in February 2015. Please contact us for more details.* ! ## Smart fuel management MPG and cost-per-mile are automatically calculated. Analyze your fuel spend from all angles - by vehicle, location, vehicle type, time frame. ! ! ## Customers Words
  45. 45. Any Shameful Comments? Refactor!
  46. 46. ! ! DOCUMENTATION CODE is 2
  47. 47. Word Cloud 3
  48. 48. 56 What  is  this   app  about?
  49. 49. You  do  it  wrong!
  50. 50. Word Cloud: dispatching + Discuss
  51. 51. Word Cloud: fuel card monitoring + Compare
  52. 52. LIVING GLOSSARY 4
  53. 53. How do I represent the Ubiquitous Language in practice?
  54. 54. Annotate domain-relevant classes Source code as reference
  55. 55. Living Glossary Living Glossary Processor Source Code & Annotations Living Glossary always up-to-date
  56. 56. Run the Living Glossary
  57. 57. Custom Doclet to export Living Glossary
  58. 58. Bounded Context comment
  59. 59. Core Concepts
  60. 60. Class comment
  61. 61. ANOTHER EXAMPLE Sent directly to end customers every week
  62. 62. Run the Living Glossary Make changes to the code rename move to /infra remove annotations change comments
  63. 63. KNOWLEDGE AUGMENTATION
  64. 64. Code
  65. 65. Bounded Contexts are there
  66. 66. Bounded Contexts are there Implicitly
  67. 67. Annotations
  68. 68. Bounded Contexts
  69. 69. Embedded Learning
  70. 70. Embedded Learning
  71. 71. Embedded Learning
  72. 72. Embedded Learning
  73. 73. Embedded Learning Learn on the job
  74. 74. LIVING DIAGRAM 4
  75. 75. Run the Living Diagram
  76. 76. Living Diagram Living Diagram Processor Source Code Living Diagram always up-to-date
  77. 77. Run the Living Diagram Make changes to the code Run the Living Diagram
  78. 78. Example: Hexagonal Architecture
  79. 79. Domain Model inside Infrastructure Outside
  80. 80. Design is already there
  81. 81. Design is already there Implicitly
  82. 82. Just rely on documented naming conventions
  83. 83. *.domain! *.infra! NOT *Test
  84. 84. Living Diagram Living Diagram Processor Source Code Living Diagram always up-to-date
  85. 85. 95 tada!
  86. 86. CONTENT FILTERING (CURATION) is KEY
  87. 87. No Value
  88. 88. 1 Diagram 1 Purpose
  89. 89. Example: Hexagonal Architecture
  90. 90. Fix the code Run the Living Diagram
  91. 91. OOPS!
  92. 92. Reality Check
  93. 93. https://www.structurizr.com/ by Simon Brown
  94. 94. https://www.structurizr.com/
  95. 95. LISTEN TO THE DOCUMENTATION FRUSTRATIONS
  96. 96. Hard to do the Living Glossary? A signal!
  97. 97. Hard to do the Living Diagrams? A signal!
  98. 98. Programming by Coincidence
  99. 99. Know what you’re doing -> Already half-documented
  100. 100. ANYBODY CAN ! APPRECIATE! IT’S A MESS
  101. 101. PRESSURE TO ! IMPROVE DESIGN
  102. 102. Simpler Design Less documentation needed
  103. 103. More standard Less documentation needed ! fogus @fogus
  104. 104. Fix your workflow Write code Write tests Write doc Write tests = write doc Write code = write doc From Mikko Ohtamaa
  105. 105. COOL!
  106. 106. In Closing
  107. 107. https://leanpub.com/livingdocumentation BUY MY BOOK!
  108. 108. Boring Documentation is dead Long Live Living Documentation!
  109. 109. Not about particular techniques ! Reconsider dealing with the knowledge
  110. 110. Share Your Ideas & Experiments
  111. 111. Questions? Did you try similar things too? Let’s discuss! @cyriux
  112. 112. Follow me @cyriux ! Slides: slideshare.net/cyriux Blog: cyrille.martraire.com ! In Paris? Join !
  113. 113. Merci

×