Living Documentation with Termites

Slide 1

Slide 1 text

Cyrille Martraire LIVING DOCUMENTATION

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

No (of course)

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 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 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

@cyriux It's not REAL Documentation

Slide 12

Slide 12 text

@cyriux Documentation sucks…

Slide 13

Slide 13 text

No content

Slide 14

Slide 14 text

USING MS OFFICE

Slide 15

Slide 15 text

*NOT* CODING

Slide 16

Slide 16 text

We love executable stu f

Slide 17

Slide 17 text

Documentation, usually.

Slide 18

Slide 18 text

Obsolete & Misleading

Slide 19

Slide 19 text

”Documentation SUCKS”

Slide 20

Slide 20 text

”TRADITIONAL Documentation SUCKS”

Slide 21

Slide 21 text

NOBODY WANTS TO mAINTAIN DOCUMENTATION!

Slide 22

Slide 22 text

Traditional DOCUMENTATION makes the work slower!

Slide 23

Slide 23 text

LEAVING DOCUMENTATION?

Slide 24

Slide 24 text

LEAVING DOCUMENTATION? YEAH, SURE.

Slide 25

Slide 25 text

But We STILL need REAL documentation!

Slide 26

Slide 26 text

Slide 27

Slide 27 text

MAKING or EVOLVING SOFTWARE is FINDING ANSWERS to LOTS OF QUESTIONS

Slide 28

Slide 28 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 29

Slide 29 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 30

Slide 30 text

THE FASTER THE ANSWER THE FASTER THE DELIVERY

Slide 31

Slide 31 text

KNOWLEDGE KNOWLEDGE KNOWLEDGE KNOWLEDGE

Slide 32

Slide 32 text

FASTER KNOWLEDGE FASTER DELIVERY

Slide 33

Slide 33 text

documentation = passing knowledge

Slide 34

Slide 34 text

Passing Knowledge to other people Transmission

Slide 35

Slide 35 text

to other people Making Accessible Passing Knowledg

Slide 36

Slide 36 text

for the future Memory Passing Knowledg

Slide 37

Slide 37 text

for the future Compliance Passing Knowledg

Slide 38

Slide 38 text

NEEDED Long-run Critical Large Audience Passing Knowledge

Slide 39

Slide 39 text

NEEDED No Waste Passing Knowledge

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

RELIABLE LOW EFFORT COLLABORATIVE INSIGHTFUL 4 KEY PRINCIPLES OF LIVING DOCUMENTATION

Slide 42

Slide 42 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 43

Slide 43 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 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 INTERNAL Documentation AUGMENTED Code READY-MADE Documentation ACCURACY mechanism We need documentation we can TRUST LIVING DOCUMENTs EVERGREEN CONTENT

Slide 45

Slide 45 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 46

Slide 46 text

Living Documentation Techniques

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

More standard Less documentation needed fogus @fogus

Slide 49

Slide 49 text

STANDARDS! =STUFF YOU’RE SUPPOSED TO KNOW ALREADY

Slide 50

Slide 50 text

CONVERSATIONS OVER DOCUMENTATION

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

No content

Slide 53

Slide 53 text

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

Slide 54

Slide 54 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 55

Slide 55 text

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

Slide 56

Slide 56 text

No content

Slide 57

Slide 57 text

What is the language of the business domain?

Slide 58

Slide 58 text

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 Processor LIVING GLOSSARY Source Code & Annotations up-to-date Living Glossary

Slide 63

Slide 63 text

Living Glossary Processor Living Glossary LIVING! Source Code & Annotations add delete rename move up-to-date

Slide 64

Slide 64 text

No content

Slide 65

Slide 65 text

Module description

Slide 66

Slide 66 text

Core Concepts

Slide 67

Slide 67 text

Class comment

Slide 68

Slide 68 text

ANOTHER EXAMPLE Sent directly to end customers every week

Slide 69

Slide 69 text

Annotate domain-relevant classes Source code as reference

Slide 70

Slide 70 text

KNOWLEDGE AUGMENTATION

Slide 71

Slide 71 text

Annotate domain-relevant classes Source code as reference

Slide 72

Slide 72 text

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

Slide 73

Slide 73 text

Code

Slide 74

Slide 74 text

Bounded Contexts are there

Slide 75

Slide 75 text

Bounded Contexts are there Implicitly

Slide 76

Slide 76 text

Annotations

Slide 77

Slide 77 text

Bounded Contexts

Slide 78

Slide 78 text

Bounded Context description

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

Slide 83

Slide 83 text

Embedded Learning Learn on the job

Slide 84

Slide 84 text

Slide 85

Slide 85 text

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

Slide 86

Slide 86 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 87

Slide 87 text

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

Slide 88

Slide 88 text

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

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

*.domai n (*.infra ) NOT *Test

Slide 95

Slide 95 text

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

Slide 96

Slide 96 text

LIVING DIAGRAM Source Code & Annotations up-to-date Living Diagram Living Diagram Processor

Slide 97

Slide 97 text

Source Code & Annotations up-to-date Living Diagram Living Diagram Processor add delete rename move

Slide 98

Slide 98 text

98 tada!

Slide 99

Slide 99 text

No content

Slide 100

Slide 100 text

CONTENT FILTERING (CURATION) is KEY

Slide 101

Slide 101 text

No content

Slide 102

Slide 102 text

No Value

Slide 103

Slide 103 text

No content

Slide 104

Slide 104 text

1 Diagram 1 Purpose

Slide 105

Slide 105 text

Example: Hexagonal Architecture

Slide 106

Slide 106 text

No content

Slide 107

Slide 107 text

No content

Slide 108

Slide 108 text

OOPS!

Slide 109

Slide 109 text

Fix the code Run the Living Diagram

Slide 110

Slide 110 text

OOPS!

Slide 111

Slide 111 text

Source Code & Annotations ok or not ok Enforced Guidelines Mecanism ENFORCED GUIDELINES

Slide 112

Slide 112 text

layeredArchitecture( ) .layer("Controller").definedBy("..controller.." ) .layer("Service").definedBy("..service.." ) .whereLayer("Controller").mayNotBeAccessedByAnyLayer( ) .whereLayer("Service").mayOnlyBeAccessedByLayers("Controlle ENFORCED GUIDELINES

Slide 113

Slide 113 text

(Is my change compliant with the architecture?) Devs

Slide 114

Slide 114 text

OOPS! YOU JUST DID IT WRONG! Devs

Slide 115

Slide 115 text

Reality Check

Slide 116

Slide 116 text

Internal Structure of a Service

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 @ fi xedincome @interests

Slide 127

Slide 127 text

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

Slide 128

Slide 128 text

Living documentation tags @acceptance-criteria @specs @wip @ fi 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 fi les

Slide 131

Slide 131 text

How often does this change?

Slide 132

Slide 132 text

Evergreen Content

Slide 133

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

Slide 134

Slide 134 text

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

Slide 135

Slide 135 text

EXEMPLARY SNIPPETS @Exemplary because developers often get ”inspiration” from existing code somewhere else in the application

Slide 136

Slide 136 text

Coding Practices

Slide 137

Slide 137 text

Executable Specs

Slide 138

Slide 138 text

Concrete scenarios

Slide 139

Slide 139 text

GUIDED TOUR

Slide 140

Slide 140 text

GUIDED TOUR

Slide 141

Slide 141 text

https://github.com/LivingDocumentation/ awesome-living-documentation Living Glossary & Diagrams

Slide 142

Slide 142 text

No content

Slide 143

Slide 143 text

Stable or Volatile? ”Big Bet 2020”

Slide 144

Slide 144 text

Stable or Volatile? ”DealerOne Premium”

Slide 145

Slide 145 text

Stable or Volatile? ”HyperDealer”

Slide 146

Slide 146 text

Stable or Volatile? ”ShowroomOptimization”

Slide 147

Slide 147 text

Stable or Volatile? ”VP of Sales Georges Fretz”

Slide 148

Slide 148 text

Stable or Volatile? ”EmployeeTimeTracking”

Slide 149

Slide 149 text

Stable or Volatile? ”threshold = 7%”

Slide 150

Slide 150 text

Stable or Volatile? ”Implemented in Java”

Slide 151

Slide 151 text

Stable or Volatile? ”Implemented in Kotlin”

Slide 152

Slide 152 text

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

Slide 153

Slide 153 text

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

Slide 154

Slide 154 text

LIVING DOCUMENTATION ++

Slide 155

Slide 155 text

Eco-System @ExternalProvider @ExposedAPI

Slide 156

Slide 156 text

Event Sourcing

Slide 157

Slide 157 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 158

Slide 158 text

Slide 159

Slide 159 text

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

Slide 160

Slide 160 text

Runtime exports

Slide 161

Slide 161 text

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