Living Documentation!Jumpstart Workshop

cyrille martraire!@cyriux

What do you expect?

And could improve your code too?

a source of frustration

not enough outdated

CONSUMING DOC

boring task prefer coding

PRODUCING DOC

we can do better…

much betterGood Documentation also

leads to better Design

Workshop

An existing Java project (from the USB drive)

!

☞ Explore, Change, Learn

Passionate developer

PARIS Since 1999

!

@cyriux

Cyrille Martraire

Paris Software Craftsmanship Community

http://www.meetup.com/paris-software-craftsmanship/

TDDBDDDDDLegacy

Documentation

Documentation(sorry)

USING MS OFFICE

*NOT* CODING

We love executable stuff

Documentation, usually.

Obsolete & Misleading

Documentation Sucks

I don’t want to maintain

documentation !

If we adopt a new mindset

What is documentation?

Question:

What is documentation?

What is documentation?the purpose of

Passing Knowledge

to other peopleTransmission

Passing Knowledge

to other peopleMaking Accessible

Passing Knowledge

for the futureMemory

Passing Knowledge

for the futureCompliance

KNOWLEDGE KNOWLEDGE KNOWLEDGE KNOWLEDGE

DOCUMENTATION NEEDED

Long-run

Critical

Large Audience

DOCUMENTATION NEEDED

No Waste

DOCUMENTATIONBecause we can often do better than

documentation

NO

MOST KNOWLEDGE IS

ALREADY THERE

Where?

ObfuscatedNon-Accessible

Fragmented

DOCUMENTATIONCapitalize on the knowledge that’s already there + a little bit more

NO

CONVERSATIONS OVER

DOCUMENTATION

!

!

Working Collectively

Workshop Now!

EVERGREEN DOCUMENT

1

README.md What’s wrong?

*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 dailyTransaction 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 MonitoringTransaction 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 readingsWhen 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 managementMPG and cost-per-mile are automatically calculated. Analyze your fuel spend from all angles - by vehicle, location, vehicle type, time frame.!!## Customers Words

Stable knowledge? Easy.

*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 dailyTransaction 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 MonitoringTransaction 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 readingsWhen 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 managementMPG and cost-per-mile are automatically calculated. Analyze your fuel spend from all angles - by vehicle, location, vehicle type, time frame.!!## Customers Words

Any Shameful Comments? Refactor!

!

!

DOCUMENTATION

CODEis

2

Word Cloud3

56

What  is  this  app  about?

You  do  it  wrong!

Word Cloud: dispatching + Discuss

Word Cloud: fuel card monitoring

+ Compare

LIVING GLOSSARY

4

How do I representthe Ubiquitous Language

in practice?

Annotate domain-relevant classesSource code as reference

Living Glossary

Living Glossary Processor

Source Code & Annotations

Living Glossary always up-to-date

Run the Living Glossary

Custom Doclet to export Living Glossary

Bounded Context comment

Core Concepts

Class comment

ANOTHER EXAMPLESent directly to end customers every week

Run the Living Glossary Make changes to the code

rename move to /infra

remove annotations change comments

KNOWLEDGE AUGMENTATION

Code

Bounded Contexts are there

Bounded Contexts are there

Implicitly

Annotations

Bounded Contexts

Embedded Learning

Embedded Learning

Embedded Learning

Embedded Learning

Embedded LearningLearn on the job

LIVING DIAGRAM

4

Run the Living Diagram

Living Diagram

Living Diagram

Processor

Source Code

Living Diagram always up-to-date

Run the Living Diagram Make changes to the code Run the Living Diagram

Example: Hexagonal Architecture

Domain Model inside Infrastructure Outside

Design is already there

Design is already thereImplicitly

Just rely on documented naming conventions

*.domain!*.infra!NOT *Test

Living Diagram

Living Diagram

Processor

Source Code

Living Diagram always up-to-date

95

tada!

CONTENT FILTERING (CURATION)

is KEY

No Value

1 Diagram 1 Purpose

Example: Hexagonal Architecture

Fix the code Run the Living Diagram

OOPS!

Reality Check

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

https://www.structurizr.com/

LISTEN TO THE DOCUMENTATION

FRUSTRATIONS

Hard to do the Living Glossary?

A signal!

Hard to do the Living Diagrams?

A signal!

Programming by

Coincidence

Know what you’re doing ->

Already half-documented

ANYBODY CAN !APPRECIATE!IT’S A MESS

PRESSURE TO !IMPROVE DESIGN

Simpler Design Less documentation needed

More standard Less documentation needed

!fogus

@fogus

Fix your workflow

Write code Write tests Write doc

Write tests = write doc Write code = write doc

From Mikko Ohtamaa

COOL!

In Closing

https://leanpub.com/livingdocumentation

BUY MY BOOK!

Boring Documentation is dead

Long Live Living Documentation!

Not about particular techniques

!

Reconsider dealing with the knowledge

Share Your Ideas & Experiments

Questions? Did you try similar things too?

Let’s discuss!@cyriux

Follow me @cyriux !

Slides: slideshare.net/cyriux Blog: cyrille.martraire.com

!

In Paris? Join !

Merci