Living Documentation (NCrafts Paris 2015, DDDx London 2015, BDX.io 2015, Codeurs en Seine 2015)
•
6 j'aime•1,797 vues
What if documentation was as fun as coding? Always up-to-date? And what if it could even improve your design? Reconsider how you invest in knowledge to accelerate delivery, with a touch of Domain-Driven Design. For more, get the book on Leanpub: https://leanpub.com/livingdocumentation
Recommandé
Recommandé
Contenu connexe
En vedette
En vedette (20)
Similaire à Living Documentation (NCrafts Paris 2015, DDDx London 2015, BDX.io 2015, Codeurs en Seine 2015)
Similaire à Living Documentation (NCrafts Paris 2015, DDDx London 2015, BDX.io 2015, Codeurs en Seine 2015) (20)
Plus de Cyrille Martraire
Plus de Cyrille Martraire (12)
Dernier
Dernier (20)
Living Documentation (NCrafts Paris 2015, DDDx London 2015, BDX.io 2015, Codeurs en Seine 2015)
- 3. And could improve your code too?
- 4. a source of frustration
- 7. we can do better…
- 8. much better Good Documentation also leads to better Design
- 12. Documentation
- 15. USING MS OFFICE
- 16. *NOT* CODING
- 17. We love executable stuff
- 20. Not Agile
- 22. 22 SO WHY U TALK OF DOC?
- 23. I’m happy with my life I love my job Back from nice vacations
- 24. I’m happy with my life I love my family We’ve happy with our little boy And recently back from nice vacations WHY MAKE LIFEMISERABLE? WHY RUINTHIS CONFERENCEWITH THIS TOPIC?
- 26. If we adopt a new mindset
- 30. Not just Javadoc Code Comments MS Office
- 31. Passing Knowledge to other people Transmission
- 32. Passing Knowledge to other people Making Accessible
- 33. Passing Knowledge for the future Memory
- 34. Passing Knowledge for the future Compliance
- 38. Imagine
- 41. WHAT FOR?
- 42. For Sarah She’s joining next week
- 43. Do you really need it written?
- 44. What about talking & answering questions?
- 47. This does not Sound like working
- 48. MISSING Trust
- 49. What about solving these issues instead? Documentation is only a symptom
- 50. Perhaps we could pair-program? or do mob-programming?
- 55. 55 Where do I put that stuff?
- 57. Bounded Contexts Explicitly define the context within which a model applies. Explicitly set boundaries in terms of team organization, usage within specific parts of the application, and physical manifestations such as code bases and database schemas. Keep the model strictly consistent within these bounds, but don’t be distracted or confused by issues outside. How do I make it real?
- 58. Ubiquitous Language A language structured around the domain model and used by all team members to connect all the activities of the team with the software. How do I make it real?
- 59. Domain Model A system of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain. How do I make it real?
- 60. 60 Where do I put that stuff?
- 61. Where do I put that stuff? For realz?!
- 62. Documentation!
- 63. How do we get all this knowledge about the domain?
- 65. DOMAIN IMMERSION
- 66. Fleet Management for Parcel Delivery
- 67. Visit on the field
- 68. Conversations
- 69. ”Live my life”
- 70. For new joiners
- 71. Domain Immersion as part of the on-boarding process
- 72. DOCUMENTATION Because we can often do better than documentation NO
- 74. How do I document my understanding of the domain?
- 75. Investigation Wall (aka Obsession Wall)
- 76. Fleet Management for Parcel Delivery 1M km/yr
- 77. What about competitors? Commercial Leaflet Website Found docs Online templates
- 81. What about documenting the behaviors? Because business people never change their mind
- 82. BDD
- 83. Scenarios Intent
- 85. Redundancy!
- 86. Redundancy! What if one changes and not the other?
- 90. Living documentation Another example @acceptance-criteria @specs @wip @fixedincome @interests
- 91. Living documentation tags @acceptance-criteria @specs @wip @fixedincome @interests
- 92. Living documentation tags @acceptance-criteria @specs @wip @fixedincome @interests Carefully crafted business knowledge too
- 93. Interactive website search by feature or tag navigate by tag navigate by feature / chapter
- 94. Living documentation + collocated markdown files thx @aloyer
- 95. back to work now
- 98. FueldCardTransaction received into FuelCardMonitoring FuelCardMonitoring queries Geocoding FuelCardMonitoring queries GPSTracking Geocoding converts address into AddressCoordinates GPSTracking provides VehicleCoordinates VehicleCoordinates between GeoDistance AddressCoordinates between GeoDistance GeoDistance compared to DistanceThreshold DistanceThreshold delivers AnomalyReport diagrammr.com
- 99. FueldCardTransaction received into FuelCardMonitoring FuelCardMonitoring queries Geocoding FuelCardMonitoring queries GPSTracking Geocoding converts address into AddressCoordinates GPSTracking provides VehicleCoordinates VehicleCoordinates between GeoDistance AddressCoordinates between GeoDistance GeoDistance compared to DistanceThreshold DistanceThreshold delivers AnomalyReport
- 100. PLAIN-TEXT DIAGRAM
- 101. In Source Control Edit in any tool Easy to diff Easy to maintain
- 102. so what about the code?
- 107. Code
- 108. WHY U NOT TALK OF DDD?
- 109. How do I materialize The Bounded Contexts in my code?
- 113. Annotations
- 114. Bounded Contexts
- 115. Embedded Learning
- 116. Embedded Learning
- 117. Embedded Learning
- 118. Embedded Learning Learn on the job
- 121. How do I represent the Ubiquitous Language in practice?
- 123. Annotate domain-relevant classes Source code as reference
- 124. LIVING GLOSSARY
- 125. Living Glossary Living Glossary Processor Source Code & Annotations Living Glossary always up-to-date
- 126. Custom Doclet to export Living Glossary
- 128. Core Concepts
- 129. Class comment
- 130. ANOTHER EXAMPLE Sent directly to end customers every week
- 131. Design
- 133. Domain Model inside Infrastructure Outside
- 134. How do I document the Design?
- 135. Well…
- 138. Literature is already there Ready-Made Documentation
- 139. Design is already there
- 140. Design is already there Implicitly
- 141. Just rely on documented naming conventions
- 143. LIVING DIAGRAM
- 144. Living Diagram Living Diagram Processor Source Code Living Diagram always up-to-date
- 145. 145
- 149. No Value
- 151. 1 Diagram 1 Purpose
- 152. https://www.structurizr.com/ by Simon Brown
- 155. Runtime exports
- 156. Runtime exports sum_{i=0}^{n}frac{ }{ } 1+rt (1+r)^{t} (1+r)^{frac{t_1 - t_0}{360}} 1+r.frac{t_1 - t_0}{365}
- 157. Runtime exports sum_{i=0}^{n}frac{ }{ } 1+rt (1+r)^{t} (1+r)^{frac{t_1 - t_0}{360}} 1+r.frac{t_1 - t_0}{365}
- 158. etc.
- 159. Make tools
- 160. ”DDD is primarily about tools”
- 164. (Sounds like MDA)
- 167. over-complicate documentation tools over over-complicate the production code
- 168. There’s more
- 169. Hard to do the Living Glossary?
- 170. Hard to do the Living Glossary? A signal!
- 171. What happens to your Ubiquitous Language in the code? Lost Translations Mixed
- 172. You may be doing DDD wrong!
- 174. Beyond Documentation Listen to the frustrations Focus on documentation Improve the product
- 175. Reality Check
- 176. 176 My code is good!
- 177. You do it wrong!
- 178. These comments suck!
- 180. Extract a word cloud from your code BAD
- 181. Extract a word cloud from your code Better
- 182. Hard to do the Living Diagrams? A signal!
- 185. Deliberate Design
- 186. Know what you’re doing -> Already half-documented
- 190. OOPS!
- 191. Beyond Documentation Ooops! This is not what I expected :( 1st generation Fix the design
- 192. ANYBODY CAN ! APPRECIATE! IT’S A MESS
- 193. PRESSURE TO ! IMPROVE DESIGN
- 194. Simpler Design Less documentation needed
- 195. More standard Less documentation needed ! fogus @fogus
- 196. Fix your workflow Write code Write tests Write doc Write tests = write doc Write code = write doc From Mikko Ohtamaa
- 197. How does it work with TDD? Refactor until it looks good
- 199. COOL!
- 200. In Closing
- 203. ”The only hope, then, for producing good documentation is to convince the programmer that it will benefit him to do so.” @JerryWeinberg
- 204. Knowledge is already there It just wants to break free
- 207. Boring Documentation is dead Long Live Living Documentation!
- 208. Not about particular techniques ! Reconsider dealing with the knowledge
- 209. Share Your Ideas & Experiments
- 211. Follow me @cyriux ! Slides: slideshare.net/cyriux Blog: cyrille.martraire.com ! In Paris? Join !
- 212. Merci