View
322
Download
0
Category
Preview:
Citation preview
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
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
Recommended