Leaving Documentation, or Living Documentation?

Some knowledge is worth sharing to accelerate the work of teams and to improve the quality of the result. Remote work only makes this concern more obvious. But the traditional techniques of documentation suffer from notorious flaws that make them unfit for modern, fast-paced delivery approaches.

It’s time to leave documentation, and to fully embrace a Living Documentation perspective instead, as a set of lightweight knowledge sharing practices that are effective in continuously changing environments.

Cyrille, the author of the book Living Documentation (Addison-Wesley Professionals) will be your guide, so that you’ll never see documentation the same way again!

Conference "The Legacy of Socrates" 7th edition, video also online: https://www.youtube.com/watch?v=icGhEOWPqB4

Transcript

1. Cyrille Martraire LEAVING DOCUMENTATION? @cyriux
2. Cyrille Martraire A TALK ABOUT DOCUMENTATION …
3. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html Termites build IMPRESSIVE nests
4. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html Do they draw blueprints to build their nests?
5. No (of course)
6. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html We humans do! (after the fact)
7. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html Thermal Control! (passive cooling)
8. http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html STIGMERGY
9. 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!
10. In the wild, DEVELOPERS WORK A BIT LIKE THAT TOO!
11. DEVELOPERS ALSO COLLABORATE MOSTLY THROUGH THE WORK (REALLY) CONVERSATIONS CODE
12. but, It’s real Documentation! NOT
13. We need REAL documentation!
14. but real Documentation
16. USING MS OFFICE
17. *NOT* CODING
18. We love executable stuff
19. Documentation, usually.
20. Obsolete & Misleading
21. ”Documentation SUCKS”
22. ”TRADITIONAL Documentation SUCKS”
23. NOBODY WANTS TO mAINTAIN DOCUMENTATION!
24. Traditional DOCUMENTATION makes the work slower!
25. LEAVING DOCUMENTATION?
26. LEAVING DOCUMENTATION? YEAH, SURE.
27. But We STILL need REAL documentation!
28. <why do you need documentation after all?>
29. MAKING or EVOLVING SOFTWARE is FINDING ANSWERS to LOTS OF QUESTIONS
30. 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
31. 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
32. THE FASTER THE ANSWER THE FASTER THE DELIVERY
33. KNOWLEDGE KNOWLEDGE KNOWLEDGE KNOWLEDGE
34. FASTER KNOWLEDGE FASTER DELIVERY
35. documentation = passing knowledge
36. Passing Knowledge to other people Transmission
37. to other people Making Accessible Passing Knowledg
38. for the future Memory Passing Knowledg
39. for the future Compliance Passing Knowledg
40. NEEDED Long-run Critical Large Audience Passing Knowledge
41. NEEDED No Waste Passing Knowledge
42. THE IDEAL Having access to just enough knowledge, just in time, that you can trust, is a driver to accelerate software delivery
43. RELIABLE LOW EFFORT COLLABORATIVE INSIGHTFUL 4 KEY PRINCIPLES OF LIVING DOCUMENTATION
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 We need documentation we can TRUST
45. 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
46. 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
47. - 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!
48. Living Documentation Techniques
49. #1 NO DOCUMENTATION (we can often do better than documentation)
50. STANDARDS! =STUFF YOU’RE SUPPOSED TO KNOW ALREADY
51. CONVERSATIONS OVER DOCUMENTATION
52. overheard pair-programming mob-programming coffee machine chat Event-Storming immersion ”Live-my-Life” … Working Collectively
54. #2 MOST KNOWLEDGE IS ALREADY THERE (it just wants to break free)
55. 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…)
56. MOST KNOWLEDGE IS ALREADY THERE Where? Obfuscated Non-Accessible Fragmented
58. What is the ”Ubiquitous Language” of the business domain? Everyone
59. WORD CLOUD
62. LIVING GLOSSARY
63. Living Glossary Living Glossary Processor Source Code & Annotations Living Glossary always up-to-date
64. Custom Doclet to export Living Glossary
65. Bounded Context description
66. Core Concepts
67. Class comment
68. Living Glossary Living Glossary Processor Source Code & Annotations Living Glossary always up-to-date Add Delete rename move always in sync!
69. ANOTHER EXAMPLE Sent directly to end customers every week
70. Annotate domain-relevant classes Source code as reference
71. KNOWLEDGE AUGMENTATION
72. Code
73. Bounded Contexts are there
74. Bounded Contexts are there Implicitly
75. Annotations
76. Bounded Contexts
77. Bounded Context description
78. Embedded Learning
79. Embedded Learning
80. Embedded Learning
81. Embedded Learning
82. Embedded Learning Learn on the job
83. <how to do knowledge augmentation>
84. #3 READY-MADE KNOWLEDGE (don’t write prose, just link to already published prose)
85. 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)
86. Create your own annotation(s) @Layer(name=””) @HexagonalArchitecture @ViewModel @DomainModel @Notification @Collaborator @ComponentRoot @Adapter(from = …, to = …) @MainStyle(style=””) @Rationale(””)
87. What’s the architecture in place ? (so that I don’t break it by mistake) Devs
88. LIVING DIAGRAM
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. *.domain (*.infra) NOT *Test
95. *.leasing *.leasing.adapters @HexagonalArchitecture.DomainModel @HexagonalArchitecture.Adapters
96. Living Diagram Living Diagram Processor Source Code Living Diagram always up-to-date
97. 97 tada!
99. CONTENT FILTERING (CURATION) is KEY
101. No Value
103. 1 Diagram 1 Purpose
104. Example: Hexagonal Architecture
107. OOPS!
108. Fix the code Run the Living Diagram
109. OOPS!
110. ENFORCED GUIDELINES
111. Enforced Guidelines Why have people go look for the knowledge when the knowledge could prompt them at the right time instead?
112. Is my change compliant with the architecture? Devs
113. Enforced Guidelines Why have people go look for the knowledge when the knowledge could prompt them at the right time instead?
114. Reality Check
115. Internal Structure of a Service
116. https://www.structurizr.com/ by Simon Brown
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 @fixedincome @interests
127. Living documentation tags @acceptance-criteria @specs @wip @fixedincome @interests
128. Living documentation tags @acceptance-criteria @specs @wip @fixedincome @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 files
131. CODE AS -INTERNAL- DOCUMENTATION
132. SHAMEFUL COMMENTS
134. Any Shameful Comments? Refactor!
136. EVERGREEN CONTENT DOCUMENT
137. *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
138. Stable knowledge? Easy.
139. Volatile knowledge? Move it out!
140. *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
141. Key Question: How frequently does this change?
142. Stable or Volatile? ”Big Bet 2020”
143. Stable or Volatile? ”DealerOne Premium”
144. Stable or Volatile? ”HyperDealer”
145. Stable or Volatile? ”ShowroomOptimization”
146. Stable or Volatile? ”VP of Sales Georges Fretz”
147. Stable or Volatile? ”EmployeeTimeTracking”
148. Stable or Volatile? ”threshold = 7%”
149. Stable or Volatile? ”Implemented in Java”
150. Stable or Volatile? ”Implemented in Kotlin”
151. Stable or Volatile? ”package com.finexpro.b2b.domain”
152. Stable or Volatile? ”This module follows an FP-style to reduce errors and ensure it is highly testable.”
153. ADR / DECISION LOG
154. Architectural Decision Records (aka Decision Log)
156. New Claim Management as Single Source of Truth until the claim is accepted by the customer Accepted on 01/12/2015 Context We want avoid confusion arising from unclear authority of data, which consumes developer time to fix 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. Decision 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).
157. … Consequences Given the legacy background, it is unfortunately necessary for some time to have a different Golden Source across the life of a claim. Still, at any point in the life of the claim, the authoritative data are clearly in one single source. This should be re-considered to move to one constant single source whenever possible. Because of that discrepancy, before the push: commands to create or update a claim are sent to Claim Management, with events sent around and in particular to LCM to sync the LCM data (Legacy claim mainframe as a Read Model). After the push: remote calls to LCM are used to update the claim in LCM, with events sent back to Claim Management to sync it (Claim Management as a Read Model).
158. … Consequences Given the legacy background, it is unfortunately necessary for some time to have a different Golden Source across the life of a claim. Still, at any point in the life of the claim, the authoritative data are clearly in one single source. This should be re-considered to move to one constant single source whenever possible. Because of that discrepancy, before the push: commands to create or update a claim are sent to Claim Management, with events sent around and in particular to LCM to sync the LCM data (Legacy claim mainframe as a Read Model). After the push: remote calls to LCM are used to update the claim in LCM, with events sent back to Claim Management to sync it (Claim Management as a Read Model). FEEL FREE TO CHANGE THAT ONCE AS SOON AS IT’S POSSIBLE!
159. PLAIN-TEXT DIAGRAM
161. 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
162. 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
163. In Source Control Edit in any tool Easy to diff Easy to maintain
164. LVING GUIDED TOUR
165. Highlight Exemplary areas of code because developers often get ”inspiration” from existing code somewhere else in the application Find Usages: @Exemplary
166. IDE as Integrated Documentation Why document by hand what your IDE can instantly answer on-demand? Find Usages: @Exemplary
167. Guided Tour
168. Guided Tour
169. LIVING DOCUMENTATION ++
170. Eco-System @ExternalProvider @ExposedAPI
171. Event Sourcing
172. Data Governance/Lineage On any DAO, mark the stored objects with their authority: @GoldenSource(”Product”) @GoldenCopy(”Customer”, rationale = ”AutonomyOverAuthority”, refresh = ”events from RabbitMQ”)
173. Augmented Code, with Metadata Github topics Consul tags Class / Package annotations Manifest at root of Repository Domains: - Credit Initiation - Credit Approval GoldenSource: - Request - Decisions @DomainModel package my.domain { … Zipkin annotations
174. Augmented Code, Microservices b2c, frontend, bff, leasing, quotation, emea backend, queue, load-levelling, email
175. Runtime exports
176. #3 LISTEN TO DOCUMENTATION FRUSTRATION (it’s feedback on the quality of your work)
177. Hard to do the Living Glossary? A signal!
178. Hard to do the Living Diagrams? A signal!
179. Programming by Coincidence
181. Know what you’re doing -> Already half-documented
182. ANYBODY CAN APPRECIATE IT’S A MESS
183. PRESSURE TO IMPROVE DESIGN
184. Simpler Design Less documentation needed
185. More standard Less documentation needed fogus @fogus
186. In Closing
187. - 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!