Living Documentation (NCrafts Paris 2015, DDDx London 2015, BDX.io 2015, Codeurs en Seine 2015)
212
Living Documentation cyrille martraire @cyriux
-
Upload
martraire-cyrille -
Category
Software
-
view
1.112 -
download
1
Transcript of Living Documentation (NCrafts Paris 2015, DDDx London 2015, BDX.io 2015, Codeurs en Seine 2015)
Living Documentation
cyrille martraire!@cyriux
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
Passionate developer
PARIS Since 1999
!
@cyriuxCyrille 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
Not Agile
Documentation Sucks
22
SO WHY U TALK OF DOC?
I’m happy with my life
I love my job
Back from nice vacations
I’m happy with my life
I love my family
We’ve happy with our little boy
And recently back from nice vacations
WHY MAKE LIFE MISERABLE?
WHY RUIN THIS CONFERENCE WITH THIS TOPIC?
If we adopt a new mindset
What is documentation?
Question:
What is documentation?
What is documentation?the purpose of
Not just Javadoc Code Comments
MS Office
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
Imagine
WHAT FOR?
For Sarah
She’s joining next week
Do
you really need
it written?
What about
talking & answering
questions?
CONVERSATIONS
High-Bandwidth
Just-In-Time
Interactive
CONVERSATIONS OVER
DOCUMENTATION
This does not
Sound like working
MISSING Trust
What about solving these issues instead?
Documentation is only a symptom
Perhaps we could pair-program?
or do mob-programming?
!
!
Working Collectively
!
!
DOCUMENTATION
CODEis
DDD!Investing in
domain knowledge
55
Where do I put that stuff?
56
DDD is abstract!
Bounded ContextsExplicitly define the context within which a model applies. Explicitly set boundaries in terms of team organization, usage within specific parts of the application, and physical manifestations such as code bases and database schemas. Keep the model strictly consistent within these bounds, but don’t be distracted or confused by issues outside.
How do I make it real?
Ubiquitous Language
A language structured around the domain model and used by all team members to connect all the activities of the team with the software.
How do I make it real?
Domain Model
A system of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain.
How do I make it real?
60
Where do I put that stuff?
Where do I put that stuff?
For realz?!
Documentation!
How do we get all thisknowledge about the domain?
Event Storming workshops
DOMAIN IMMERSION
Fleet Management for Parcel Delivery
Visit on the field
Conversations
”Live my life”
For new joiners
Domain Immersionas part of the on-boarding process
DOCUMENTATIONBecause we can often do better than
documentation
NO
How do I documentmy understanding of the domain?
Investigation Wall (aka Obsession Wall)
Fleet Management for Parcel Delivery
1M km/yr
What about competitors?
Commercial Leaflet
Website
Found docs
Online templates
Stable knowledge? Easy.
EVERGREEN DOCUMENT
What about documenting the
behaviors?
What about documenting the
behaviors?Because business people
never change their mind
BDD
Scenarios
Intent
Scenarios
Concrete examples
Redundancy!
Redundancy!What if one changes and not the other?
Living Documentation
Living documentationFree comments
Living documentationAnother example
@acceptance-criteria @specs @wip @fixedincome @interests
Living documentation
tags@acceptance-criteria @specs @wip @fixedincome @interests
Living documentation
tags@acceptance-criteria @specs @wip @fixedincome @interests
Carefully crafted business knowledge too
Interactive websitesearch by feature or tag
navigate by tag
navigate by feature / chapter
Living documentation
+ collocated markdown files
thx @aloyer
back to work now
Fraud detection mechanism
NAPKIN SKETCH
Throw-Away
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
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
PLAIN-TEXT DIAGRAM
In Source Control Edit in any tool
Easy to diff Easy to maintain
so what about the code?
Any Shameful Comments? Refactor!
!
!
DOCUMENTATION
CODEis
Code
WHY U NOT
TALK OF DDD?
How do I materializeThe Bounded Contexts
in my code?
Bounded Contexts are there
Bounded Contexts are there
Implicitly
KNOWLEDGE AUGMENTATION
Annotations
Bounded Contexts
Embedded Learning
Embedded Learning
Embedded Learning
Embedded LearningLearn on the job
Carefully crafted Ubiquitous Language
How do I representthe Ubiquitous Language
in practice?
Ubiquitous Language is there
Annotate domain-relevant classesSource code as reference
LIVING GLOSSARY
Living Glossary
Living Glossary Processor
Source Code & Annotations
Living Glossary always up-to-date
Custom Doclet to export Living Glossary
Bounded Context comment
Core Concepts
Class comment
ANOTHER EXAMPLESent directly to end customers every week
Design
Example: Hexagonal Architecture
Domain Model inside Infrastructure Outside
How do I documentthe Design?
Well…
Literature is already there
Alistair Cockburn
137
Literature is already there
Ready-Made Documentation
Design is already there
Design is already thereImplicitly
Just rely on documented naming conventions
*.domain!*.infra!NOT *Test
LIVING DIAGRAM
Living Diagram
Living Diagram
Processor
Source Code
Living Diagram always up-to-date
145
CONTENT FILTERING (CURATION)
is KEY
No Value
1 Diagram 1 Purpose
Moar Living Documentation
Plz!
Runtime exports
Runtime exports
\sum_{i=0}^{n}\frac{ }{ }
1+rt (1+r)^{t}
(1+r)^{\frac{t_1 - t_0}{360}} 1+r.\frac{t_1 - t_0}{365}
Runtime exports
\sum_{i=0}^{n}\frac{ }{ }
1+rt (1+r)^{t}
(1+r)^{\frac{t_1 - t_0}{360}} 1+r.\frac{t_1 - t_0}{365}
etc.
Make tools
”DDD is primarily about tools”
Avoid Production Work!
(Sounds like MDA)
over-complicate documentation tools over
over-complicate the production code
There’s more
Hard to do the Living Glossary?
Hard to do the Living Glossary?
A signal!
What happens to your Ubiquitous Language
in the code?
Lost Translations Mixed
You may be doing DDD wrong!
LISTEN TO THE DOCUMENTATION
FRUSTRATIONS
Beyond Documentation
Listen to the frustrations
Focus on documentation
Improve the product
Reality Check
176
My code is good!
You do it wrong!
These comments suck!
Any Shameful Comments? Refactor!
Extract a word cloud from your code BAD
Extract a word cloud from your code Better
Hard to do the Living Diagrams?
A signal!
Programming by
Coincidence
Deliberate Design
Know what you’re doing ->
Already half-documented
Example: Hexagonal Architecture
OOPS!
Beyond Documentation
Ooops! This is not what I expected :(
1st generation
Fix the design
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
How does it work with TDD?
Refactor until it looks good
Documentation Skills ==
Design Skills
COOL!
In Closing
https://leanpub.com/livingdocumentation
BUY MY BOOK!
”The only hope, then, for producing good documentation is to convince the programmer that it will benefit him to do so.”
@JerryWeinberg
Knowledge is already there
It just wants to break free
Boring Documentation is dead
Long Live Living Documentation!
Not about particular techniques
!
Reconsider dealing with the knowledge
Share Your Ideas & Experiments
Follow me @cyriux !
Slides: slideshare.net/cyriux Blog: cyrille.martraire.com
!
In Paris? Join !
Merci
