Leaving Documentation, or Living Documentation?

Slide 1

Slide 1 text

Cyrille Martraire LEAVING DOCUMENTATION? @cyriux

Slide 2

Slide 2 text

Cyrille Martraire A TALK ABOUT DOCUMENTATION …

Slide 3

Slide 3 text

http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html Termites build IMPRESSIVE nests

Slide 4

Slide 4 text

http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html Do they draw blueprints to build their nests?

Slide 5

Slide 5 text

No (of course)

Slide 6

Slide 6 text

http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html We humans do! (after the fact)

Slide 7

Slide 7 text

http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html Thermal Control! (passive cooling)

Slide 8

Slide 8 text

http://termitewood.com/termite-nests-secret-of-the-architectural-skill.html STIGMERGY

Slide 9

Slide 9 text

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!

Slide 10

Slide 10 text

In the wild, DEVELOPERS WORK A BIT LIKE THAT TOO!

Slide 11

Slide 11 text

DEVELOPERS ALSO COLLABORATE MOSTLY THROUGH THE WORK (REALLY) CONVERSATIONS CODE

Slide 12

Slide 12 text

but, It’s real Documentation! NOT

Slide 13

Slide 13 text

We need REAL documentation!

Slide 14

Slide 14 text

but real Documentation

Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

USING MS OFFICE

Slide 17

Slide 17 text

*NOT* CODING

Slide 18

Slide 18 text

We love executable stuﬀ

Slide 19

Slide 19 text

Documentation, usually.

Slide 20

Slide 20 text

Obsolete & Misleading

Slide 21

Slide 21 text

”Documentation SUCKS”

Slide 22

Slide 22 text

”TRADITIONAL Documentation SUCKS”

Slide 23

Slide 23 text

NOBODY WANTS TO mAINTAIN DOCUMENTATION!

Slide 24

Slide 24 text

Traditional DOCUMENTATION makes the work slower!

Slide 25

Slide 25 text

LEAVING DOCUMENTATION?

Slide 26

Slide 26 text

LEAVING DOCUMENTATION? YEAH, SURE.

Slide 27

Slide 27 text

But We STILL need REAL documentation!

Slide 28

Slide 28 text

Slide 29

Slide 29 text

MAKING or EVOLVING SOFTWARE is FINDING ANSWERS to LOTS OF QUESTIONS

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

THE FASTER THE ANSWER THE FASTER THE DELIVERY

Slide 33

Slide 33 text

KNOWLEDGE KNOWLEDGE KNOWLEDGE KNOWLEDGE

Slide 34

Slide 34 text

FASTER KNOWLEDGE FASTER DELIVERY

Slide 35

Slide 35 text

documentation = passing knowledge

Slide 36

Slide 36 text

Passing Knowledge to other people Transmission

Slide 37

Slide 37 text

to other people Making Accessible Passing Knowledg

Slide 38

Slide 38 text

for the future Memory Passing Knowledg

Slide 39

Slide 39 text

for the future Compliance Passing Knowledg

Slide 40

Slide 40 text

NEEDED Long-run Critical Large Audience Passing Knowledge

Slide 41

Slide 41 text

NEEDED No Waste Passing Knowledge

Slide 42

Slide 42 text

THE IDEAL Having access to just enough knowledge, just in time, that you can trust, is a driver to accelerate software delivery

Slide 43

Slide 43 text

RELIABLE LOW EFFORT COLLABORATIVE INSIGHTFUL 4 KEY PRINCIPLES OF LIVING DOCUMENTATION

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

- 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!

Slide 48

Slide 48 text

Living Documentation Techniques

Slide 49

Slide 49 text

#1 NO DOCUMENTATION (we can often do better than documentation)

Slide 50

Slide 50 text

STANDARDS! =STUFF YOU’RE SUPPOSED TO KNOW ALREADY

Slide 51

Slide 51 text

CONVERSATIONS OVER DOCUMENTATION

Slide 52

Slide 52 text

overheard pair-programming mob-programming coffee machine chat Event-Storming immersion ”Live-my-Life” … Working Collectively

Slide 53

Slide 53 text

No content

Slide 54

Slide 54 text

#2 MOST KNOWLEDGE IS ALREADY THERE (it just wants to break free)

Slide 55

Slide 55 text

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…)

Slide 56

Slide 56 text

MOST KNOWLEDGE IS ALREADY THERE Where? Obfuscated Non-Accessible Fragmented

Slide 57

Slide 57 text

No content

Slide 58

Slide 58 text

What is the ”Ubiquitous Language” of the business domain? Everyone

Slide 59

Slide 59 text

WORD CLOUD

Slide 60

Slide 60 text

No content

Slide 61

Slide 61 text

No content

Slide 62

Slide 62 text

LIVING GLOSSARY

Slide 63

Slide 63 text

Living Glossary Living Glossary Processor Source Code & Annotations Living Glossary always up-to-date

Slide 64

Slide 64 text

Custom Doclet to export Living Glossary

Slide 65

Slide 65 text

Bounded Context description

Slide 66

Slide 66 text

Core Concepts

Slide 67

Slide 67 text

Class comment

Slide 68

Slide 68 text

Living Glossary Living Glossary Processor Source Code & Annotations Living Glossary always up-to-date Add Delete rename move always in sync!

Slide 69

Slide 69 text

ANOTHER EXAMPLE Sent directly to end customers every week

Slide 70

Slide 70 text

Annotate domain-relevant classes Source code as reference

Slide 71

Slide 71 text

KNOWLEDGE AUGMENTATION

Slide 72

Slide 72 text

Code

Slide 73

Slide 73 text

Bounded Contexts are there

Slide 74

Slide 74 text

Bounded Contexts are there Implicitly

Slide 75

Slide 75 text

Annotations

Slide 76

Slide 76 text

Bounded Contexts

Slide 77

Slide 77 text

Bounded Context description

Slide 78

Slide 78 text

Embedded Learning

Slide 79

Slide 79 text

Embedded Learning

Slide 80

Slide 80 text

Embedded Learning

Slide 81

Slide 81 text

Embedded Learning

Slide 82

Slide 82 text

Embedded Learning Learn on the job

Slide 83

Slide 83 text

Slide 84

Slide 84 text

#3 READY-MADE KNOWLEDGE (don’t write prose, just link to already published prose)

Slide 85

Slide 85 text

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)

Slide 86

Slide 86 text

Create your own annotation(s) @Layer(name=””) @HexagonalArchitecture @ViewModel @DomainModel @Notification @Collaborator @ComponentRoot @Adapter(from = …, to = …) @MainStyle(style=””) @Rationale(””)

Slide 87

Slide 87 text

What’s the architecture in place ? (so that I don’t break it by mistake) Devs

Slide 88

Slide 88 text

LIVING DIAGRAM

Slide 89

Slide 89 text

Example: Hexagonal Architecture

Slide 90

Slide 90 text

Domain Model inside Infrastructure Outside

Slide 91

Slide 91 text

Design is already there

Slide 92

Slide 92 text

Design is already there Implicitly

Slide 93

Slide 93 text

Just rely on documented naming conventions

Slide 94

Slide 94 text

*.domain (*.infra) NOT *Test

Slide 95

Slide 95 text

*.leasing *.leasing.adapters @HexagonalArchitecture.DomainModel @HexagonalArchitecture.Adapters

Slide 96

Slide 96 text

Living Diagram Living Diagram Processor Source Code Living Diagram always up-to-date

Slide 97

Slide 97 text

97 tada!

Slide 98

Slide 98 text

No content

Slide 99

Slide 99 text

CONTENT FILTERING (CURATION) is KEY

Slide 100

Slide 100 text

No content

Slide 101

Slide 101 text

No Value

Slide 102

Slide 102 text

No content

Slide 103

Slide 103 text

1 Diagram 1 Purpose

Slide 104

Slide 104 text

Example: Hexagonal Architecture

Slide 105

Slide 105 text

No content

Slide 106

Slide 106 text

No content

Slide 107

Slide 107 text

OOPS!

Slide 108

Slide 108 text

Fix the code Run the Living Diagram

Slide 109

Slide 109 text

OOPS!

Slide 110

Slide 110 text

ENFORCED GUIDELINES

Slide 111

Slide 111 text

Enforced Guidelines Why have people go look for the knowledge when the knowledge could prompt them at the right time instead?

Slide 112

Slide 112 text

Is my change compliant with the architecture? Devs

Slide 113

Slide 113 text

Enforced Guidelines Why have people go look for the knowledge when the knowledge could prompt them at the right time instead?

Slide 114

Slide 114 text

Reality Check

Slide 115

Slide 115 text

Internal Structure of a Service

Slide 116

Slide 116 text

https://www.structurizr.com/ by Simon Brown

Slide 117

Slide 117 text

No content

Slide 118

Slide 118 text

What about the business behaviours? Everyone

Slide 119

Slide 119 text

BEHAVIOR- DRIVEN DEVELOPMENT

Slide 120

Slide 120 text

Scenarios Intent

Slide 121

Slide 121 text

Scenarios Concrete examples

Slide 122

Slide 122 text

Living documentation Free comments

Slide 123

Slide 123 text

Redundancy!

Slide 124

Slide 124 text

Redundancy! What it one changes and not the other?

Slide 125

Slide 125 text

No content

Slide 126

Slide 126 text

Living documentation Another example @acceptance-criteria @specs @wip @ﬁxedincome @interests

Slide 127

Slide 127 text

Living documentation tags @acceptance-criteria @specs @wip @ﬁxedincome @interests

Slide 128

Slide 128 text

Living documentation tags @acceptance-criteria @specs @wip @ﬁxedincome @interests Carefully crafted business knowledge too

Slide 129

Slide 129 text

Interactive website search by feature or tag navigate by tag navigate by feature / chapter

Slide 130

Slide 130 text

Living documentation + collocated markdown ﬁles

Slide 131

Slide 131 text

CODE AS -INTERNAL- DOCUMENTATION

Slide 132

Slide 132 text

SHAMEFUL COMMENTS

Slide 133

Slide 133 text

No content

Slide 134

Slide 134 text

Any Shameful Comments? Refactor!

Slide 135

Slide 135 text

No content

Slide 136

Slide 136 text

EVERGREEN CONTENT DOCUMENT

Slide 137

Slide 137 text

*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

Slide 138

Slide 138 text

Stable knowledge? Easy.

Slide 139

Slide 139 text

Volatile knowledge? Move it out!

Slide 140

Slide 140 text

Slide 141

Slide 141 text

Key Question: How frequently does this change?

Slide 142

Slide 142 text

Stable or Volatile? ”Big Bet 2020”

Slide 143

Slide 143 text

Stable or Volatile? ”DealerOne Premium”

Slide 144

Slide 144 text

Stable or Volatile? ”HyperDealer”

Slide 145

Slide 145 text

Stable or Volatile? ”ShowroomOptimization”

Slide 146

Slide 146 text

Stable or Volatile? ”VP of Sales Georges Fretz”

Slide 147

Slide 147 text

Stable or Volatile? ”EmployeeTimeTracking”

Slide 148

Slide 148 text

Stable or Volatile? ”threshold = 7%”

Slide 149

Slide 149 text

Stable or Volatile? ”Implemented in Java”

Slide 150

Slide 150 text

Stable or Volatile? ”Implemented in Kotlin”

Slide 151

Slide 151 text

Stable or Volatile? ”package com.finexpro.b2b.domain”

Slide 152

Slide 152 text

Stable or Volatile? ”This module follows an FP-style to reduce errors and ensure it is highly testable.”

Slide 153

Slide 153 text

ADR / DECISION LOG

Slide 154

Slide 154 text

Architectural Decision Records (aka Decision Log)

Slide 155

Slide 155 text

No content

Slide 156

Slide 156 text

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 ﬁ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. 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).

Slide 157

Slide 157 text

… 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).

Slide 158

Slide 158 text

Slide 159

Slide 159 text

PLAIN-TEXT DIAGRAM

Slide 160

Slide 160 text

No content

Slide 161

Slide 161 text

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

Slide 162

Slide 162 text

Slide 163

Slide 163 text

In Source Control Edit in any tool Easy to diff Easy to maintain

Slide 164

Slide 164 text

LVING GUIDED TOUR

Slide 165

Slide 165 text

Highlight Exemplary areas of code because developers often get ”inspiration” from existing code somewhere else in the application Find Usages: @Exemplary

Slide 166

Slide 166 text

IDE as Integrated Documentation Why document by hand what your IDE can instantly answer on-demand? Find Usages: @Exemplary

Slide 167

Slide 167 text

Guided Tour

Slide 168

Slide 168 text

Guided Tour

Slide 169

Slide 169 text

LIVING DOCUMENTATION ++

Slide 170

Slide 170 text

Eco-System @ExternalProvider @ExposedAPI

Slide 171

Slide 171 text

Event Sourcing

Slide 172

Slide 172 text

Data Governance/Lineage On any DAO, mark the stored objects with their authority: @GoldenSource(”Product”) @GoldenCopy(”Customer”, rationale = ”AutonomyOverAuthority”, refresh = ”events from RabbitMQ”)

Slide 173

Slide 173 text

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

Slide 174

Slide 174 text

Augmented Code, Microservices b2c, frontend, bﬀ, leasing, quotation, emea backend, queue, load-levelling, email

Slide 175

Slide 175 text

Runtime exports

Slide 176

Slide 176 text

#3 LISTEN TO DOCUMENTATION FRUSTRATION (it’s feedback on the quality of your work)