Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Leaving Documentation, or Living Documentation?

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

51dec3feb906404b8564a3c31d1050f3?s=128

Cyrille Martraire

September 22, 2021
Tweet

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

  15. None
  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
  53. None
  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

  57. None
  58. What is the ”Ubiquitous Language” of the business domain? Everyone

  59. WORD CLOUD

  60. None
  61. None
  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!

  98. None
  99. CONTENT FILTERING (CURATION) is KEY

  100. None
  101. No Value

  102. None
  103. 1 Diagram 1 Purpose

  104. Example: Hexagonal Architecture

  105. None
  106. None
  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

  117. None
  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?

  125. None
  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

  133. None
  134. Any Shameful Comments? Refactor!

  135. None
  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)

  155. None
  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

  160. None
  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

  180. None
  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!
  188. None
  189. None