Living Documentation with Termites

Living Documentation is inspired by the biological phenomenon of stigmergy, just like termites. We'll see how we benefit from that insight to share knowledge effectively,

Transcript

1. Cyrille Martraire LIVING DOCUMENTATION
2. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html Termites build IMPRESSIVE nests
3. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html Do they draw blueprints to build their nests?
4. No (of course)
5. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html We humans do! (after the fact)
6. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html Thermal Control! (passive cooling)
7. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html STIGMERGY
8. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html STIGMERGY THE WORK ITSELF, ie THE NEST UNDER CONSTRUCTION CHEMICAL MARKERS ON THE WORK ITSELF + No diagrams!
9. In the wild, DEVELOPERS WORK A BIT LIKE THAT TOO!
10. DEVELOPERS ALSO COLLABORATE MOSTLY THROUGH THE WORK (REALLY) CONVERSATIONS CODE
11. @cyriux It's not REAL Documentation
12. @cyriux Documentation sucks…
14. USING MS OFFICE
15. *NOT* CODING
16. We love executable stu f
17. Documentation, usually.
18. Obsolete & Misleading
19. ”Documentation SUCKS”
20. ”TRADITIONAL Documentation SUCKS”
21. NOBODY WANTS TO mAINTAIN DOCUMENTATION!
22. Traditional DOCUMENTATION makes the work slower!
23. LEAVING DOCUMENTATION?
24. LEAVING DOCUMENTATION? YEAH, SURE.
25. But We STILL need REAL documentation!
26. <why do you need documentation after all?>
27. MAKING or EVOLVING SOFTWARE is FINDING ANSWERS to LOTS OF QUESTIONS
28. What’s the precise criteria to be VIP? Do we already have any concept of that in our system? Hey devs, by the way can you tell how this calculation is done? Do we support this case? How much do we depend on this third party provider? Hey devs, can you check the current rate grid being used in production? Non-Devs
29. Is that already done somewhere in the system? Can I remove this useless(?) ugly(!) thing? What could break if I change that? Where’s a good example of what I’m doing done well in this context? What is this module about? Why did they do it this (stupid?) way? What other parts are used by this part which fails? Where should I add this change? Can I make this field mutable? What other components use my system? How do I deliver my change? Is my change compliant with the architecture? Devs
30. THE FASTER THE ANSWER THE FASTER THE DELIVERY
31. KNOWLEDGE KNOWLEDGE KNOWLEDGE KNOWLEDGE
32. FASTER KNOWLEDGE FASTER DELIVERY
33. documentation = passing knowledge
34. Passing Knowledge to other people Transmission
35. to other people Making Accessible Passing Knowledg
36. for the future Memory Passing Knowledg
37. for the future Compliance Passing Knowledg
38. NEEDED Long-run Critical Large Audience Passing Knowledge
39. NEEDED No Waste Passing Knowledge
40. THE IDEAL Having access to just enough knowledge, just in time, that you can trust, is a driver to accelerate software delivery
41. RELIABLE LOW EFFORT COLLABORATIVE INSIGHTFUL 4 KEY PRINCIPLES OF LIVING DOCUMENTATION
42. We Embrace Continuous Change We Like to Write Code NOT Prose We Don’t Have Time For Documentation We Want To Have Fun We Want To Be Lazy KEY IDEAS We need documentation we can TRUST
43. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html STIGMERGY Most Knowledge Is Already There In the System Augment the Code With Markers to make it Knowledge- Complete + for developers
44. We Embrace Continuous Change We Like to Write Code NOT Prose We Don’t Have Time For Documentation We Want To Have Fun We Want To Be Lazy KEY IDEAS INTERNAL Documentation AUGMENTED Code READY-MADE Documentation ACCURACY mechanism We need documentation we can TRUST LIVING DOCUMENTs EVERGREEN CONTENT
45. - Living Documentation: Continuous Knowledge Sharing by Design - By Cyrille Martraire - Published Jun 4, 2019 by Addison-Wesley Professional. - ISBN-10: 0-13-468932-1 - ISBN-13: 978-0-13-468932-6 BUY THE BOOK!
46. Living Documentation Techniques
47. #1 NO DOCUMENTATION (we can often do better than documentation)
48. More standard Less documentation needed fogus @fogus
49. STANDARDS! =STUFF YOU’RE SUPPOSED TO KNOW ALREADY
50. CONVERSATIONS OVER DOCUMENTATION
51. overheard pair-programming mob-programming coffee machine chat Event-Storming immersion ”Live-my-Life” … Working Collectively
53. #2 MOST KNOWLEDGE IS ALREADY THERE (it just wants to break free)
54. Some Examples code, types, tests, annotations, naming, patterns, folders tree, github organisation, commits history, commit comments, tools config / history, tools search / navigation, emails, registries (Consul…), runtime traces (Zipkin, conformity monkey…)
55. MOST KNOWLEDGE IS ALREADY THERE Where? Obfuscated Non-Accessible Fragmented
57. What is the language of the business domain?
58. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html STIGMERGY Most Knowledge Is Already There In the System Augment the Code With Markers to make it Knowledge- Complete + for developers
59. WORD CLOUD
62. Living Glossary Processor LIVING GLOSSARY Source Code & Annotations up-to-date Living Glossary
63. Living Glossary Processor Living Glossary LIVING! Source Code & Annotations add delete rename move up-to-date
65. Module description
66. Core Concepts
67. Class comment
68. ANOTHER EXAMPLE Sent directly to end customers every week
69. Annotate domain-relevant classes Source code as reference
70. KNOWLEDGE AUGMENTATION
71. Annotate domain-relevant classes Source code as reference
72. Augmented Code, with Metadata Github topics Consul tags Class / Package annotations Manifest at root of Repository Domains: - Credit Initiatio n - Credit Approva l GoldenSource : - Reques t - Decisions @DomainMode l package my.domain { … Zipkin annotations
73. Code
74. Bounded Contexts are there
75. Bounded Contexts are there Implicitly
76. Annotations
77. Bounded Contexts
78. Bounded Context description
79. Embedded Learning
80. Embedded Learning
81. Embedded Learning
82. Embedded Learning
83. Embedded Learning Learn on the job
84. <how to do knowledge augmentation>
85. #3 READY-MADE KNOWLEDGE (don’t write prose, just link to already published prose)
86. Patterns as Ready-Made Design Knowledge BackendForFrontEnd (Sam Newman) Strangler Application (Martin Fowler) HexagonalArchitecture (Alistair Cockburn) Correlation ID (Gregor Hohpe) ComponentRoot (Mark Seemann) AntiCorruptionLayer (Eric Evans) Interpreter (GoF) Adapter (GoF) NullObject (Bobby Woolf)
87. Create your own annotation(s) @Layer(name=””) @HexagonalArchitecture @ViewModel @DomainModel @Notification @Collaborator @ComponentRoot @Adapter(from = …, to = …) @MainStyle(style=””) @Rationale(””)
88. What’s the architecture in place ? (so that I don’t break it by mistake) Devs
89. Example: Hexagonal Architecture
90. Domain Model inside Infrastructure Outside
91. Design is already there
92. Design is already there Implicitly
93. Just rely on documented naming conventions
94. *.domai n (*.infra ) NOT *Test
95. *.leasin g *.leasing.adapters @HexagonalArchitecture.DomainModel @HexagonalArchitecture.Adapters
96. LIVING DIAGRAM Source Code & Annotations up-to-date Living Diagram Living Diagram Processor
97. Source Code & Annotations up-to-date Living Diagram Living Diagram Processor add delete rename move
98. 98 tada!
100. CONTENT FILTERING (CURATION) is KEY
102. No Value
104. 1 Diagram 1 Purpose
105. Example: Hexagonal Architecture
108. OOPS!
109. Fix the code Run the Living Diagram
110. OOPS!
111. Source Code & Annotations ok or not ok Enforced Guidelines Mecanism ENFORCED GUIDELINES
112. layeredArchitecture( ) .layer("Controller").definedBy("..controller.." ) .layer("Service").definedBy("..service.." ) .whereLayer("Controller").mayNotBeAccessedByAnyLayer( ) .whereLayer("Service").mayOnlyBeAccessedByLayers("Controlle ENFORCED GUIDELINES
113. (Is my change compliant with the architecture?) Devs
114. OOPS! YOU JUST DID IT WRONG! Devs
115. Reality Check
116. Internal Structure of a Service
118. What about the business behaviours? Everyone
119. BEHAVIOR- DRIVEN DEVELOPMENT
120. Scenarios Intent
121. Scenarios Concrete examples
122. Living documentation Free comments
123. Redundancy!
124. Redundancy! What it one changes and not the other?
126. Living documentation Another example @acceptance-criteria @specs @wip @ fi xedincome @interests
127. Living documentation tags @acceptance-criteria @specs @wip @ fi xedincome @interests
128. Living documentation tags @acceptance-criteria @specs @wip @ fi xedincome @interests Carefully crafted business knowledge too
129. Interactive website search by feature or tag navigate by tag navigate by feature / chapter
130. Living documentation + collocated markdown fi les
131. How often does this change?
132. Evergreen Content
133. *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 dail y 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 Monitorin g 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 reading s 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 managemen t MPG and cost-per-mile are automatically calculated. Analyze your fuel spend from all angles - by vehicle, location, vehicle type, time frame . ## Customers Words move any volatile knowledge out!
134. New Claim Management as Single Source of Truth until the claim is accepted by the custome r Accepted on 01/12/2015 Contex t We want avoid confusion arising from unclear authority of data, which consumes developer time to fi x failing reconciliations. This requires that only source of truth (aka Golden Source) can exist at any point in time for a given piece of domain data. Decisio n We decide that Claim Management is the only source of truth (aka Golden Source) for Claim on claim inception and until the claim is accepted by the customer, at which time it is pushed to the legacy claim mainframe. From the moment it is pushed, the only source of truth is the legacy claim mainframe (LCM). ADR Decision Log
135. EXEMPLARY SNIPPETS @Exemplary because developers often get ”inspiration” from existing code somewhere else in the application
136. Coding Practices
137. Executable Specs
138. Concrete scenarios
139. GUIDED TOUR
140. GUIDED TOUR
141. https://github.com/LivingDocumentation/ awesome-living-documentation Living Glossary & Diagrams
143. Stable or Volatile? ”Big Bet 2020”
144. Stable or Volatile? ”DealerOne Premium”
145. Stable or Volatile? ”HyperDealer”
146. Stable or Volatile? ”ShowroomOptimization”
147. Stable or Volatile? ”VP of Sales Georges Fretz”
148. Stable or Volatile? ”EmployeeTimeTracking”
149. Stable or Volatile? ”threshold = 7%”
150. Stable or Volatile? ”Implemented in Java”
151. Stable or Volatile? ”Implemented in Kotlin”
152. Stable or Volatile? ”package com.finexpro.b2b.domain”
153. Stable or Volatile? ”This module follows an FP-style to reduce errors and ensure it is highly testable.”
154. LIVING DOCUMENTATION ++
155. Eco-System @ExternalProvider @ExposedAPI
156. Event Sourcing
157. Data Governance/Lineage On any DAO, mark the stored objects with their authority: @GoldenSource(”Product”) @GoldenCopy(”Customer”, rationale = ”AutonomyOverAuthority”, refresh = ”events from RabbitMQ”)
158. Augmented Code, with Metadata Github topics Consul tags Class / Package annotations Manifest at root of Repository Domains: - Credit Initiatio n - Credit Approva l GoldenSource : - Reques t - Decisions @DomainMode l package my.domain { … Zipkin annotations
159. Augmented Code, Microservices b2c, frontend, b ff , leasing, quotation, emea backend, queue, load-levelling, email
160. Runtime exports
161. #3 LISTEN TO DOCUMENTATION FRUSTRATION (it’s feedback on the quality of your work)
162. Hard to do the Living Glossary? A signal!
163. Hard to do the Living Diagrams? A signal!
164. Programming by Coincidence
166. Know what you’re doing -> Already half-documented
167. ANYBODY CAN APPRECIAT E IT’S A MESS
168. PRESSURE TO IMPROVE DESIGN
169. Simpler Design Less documentation needed
170. In Closing
171. - Living Documentation: Continuous Knowledge Sharing by Design - By Cyrille Martraire - Published Jun 4, 2019 by Addison-Wesley Professional. - ISBN-10: 0-13-468932-1 - ISBN-13: 978-0-13-468932-6 BUY THE BOOK!