Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
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 better
Good 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/
TDD
BDD
DDD
Legacy
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 people
Transmission
Passing Knowledge
to other people
Making Accessible
Passing Knowledge
for the future
Memory
Passing Knowledge
for the future
Compliance
KNOWLEDGE
KNOWLEDGE
KNOWLEDGE
KNOWLEDGE
DOCUMENTATION
NEEDED
Long-run
Critical
Large Audience
DOCUMENTATION
NEEDED
No Waste
DOCUMENTATION
Because we can often do better than
documentation
NO
MOST KNOWLEDGE
IS
ALREADY THERE
Where?
Obfuscated
Non-Accessible
Fragmented
DOCUMENTATION
Capitalize 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...
Stable knowledge?
Easy.
*Shamelessly stolen from the nicely presented competitor Fleetio Fleet Management solution*	
[Fleetio](https://www.fleetio...
Any Shameful
Comments?
Refactor!
!
!
DOCUMENTATION
CODE
is
2
Word Cloud
3
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 represent
the Ubiquitous Language
in practice?
Annotate domain-relevant classes
Source 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 EXAMPLE
Sent 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 Learning
Learn 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 there
Implicitly
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
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015
Upcoming SlideShare
Loading in …5
×

Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015

1,163 views

Published on

Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015

Published in: Software
  • Be the first to comment

Cyrille Martraire: Living Documentation Jumpstart at I T.A.K.E. Unconference 2015

  1. 1. Living Documentation! Jumpstart Workshop cyrille martraire! @cyriux
  2. 2. What do you expect?
  3. 3. And could improve your code too?
  4. 4. a source of frustration
  5. 5. not enough outdated CONSUMING DOC
  6. 6. boring task prefer coding PRODUCING DOC
  7. 7. we can do better…
  8. 8. much better Good Documentation also leads to better Design
  9. 9. Workshop
  10. 10. An existing Java project (from the USB drive) ! ☞ Explore, Change, Learn
  11. 11. Passionate developer PARIS Since 1999 ! @cyriux Cyrille Martraire
  12. 12. Paris Software Craftsmanship Community http://www.meetup.com/paris-software-craftsmanship/
  13. 13. TDD BDD DDD Legacy
  14. 14. Documentation
  15. 15. Documentation (sorry)
  16. 16. USING MS OFFICE
  17. 17. *NOT* CODING
  18. 18. We love executable stuff
  19. 19. Documentation, usually.
  20. 20. Obsolete & Misleading
  21. 21. Documentation Sucks
  22. 22. I don’t want to maintain documentation !
  23. 23. If we adopt a new mindset
  24. 24. What is documentation? Question:
  25. 25. What is documentation?
  26. 26. What is documentation?the purpose of
  27. 27. Passing Knowledge to other people Transmission
  28. 28. Passing Knowledge to other people Making Accessible
  29. 29. Passing Knowledge for the future Memory
  30. 30. Passing Knowledge for the future Compliance
  31. 31. KNOWLEDGE KNOWLEDGE KNOWLEDGE KNOWLEDGE
  32. 32. DOCUMENTATION NEEDED Long-run Critical Large Audience
  33. 33. DOCUMENTATION NEEDED No Waste
  34. 34. DOCUMENTATION Because we can often do better than documentation NO
  35. 35. MOST KNOWLEDGE IS ALREADY THERE Where? Obfuscated Non-Accessible Fragmented
  36. 36. DOCUMENTATION Capitalize on the knowledge that’s already there + a little bit more NO
  37. 37. CONVERSATIONS OVER DOCUMENTATION
  38. 38. ! Working Collectively
  39. 39. Workshop Now!
  40. 40. EVERGREEN DOCUMENT 1
  41. 41. README.md What’s wrong?
  42. 42. *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
  43. 43. Stable knowledge? Easy.
  44. 44. *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
  45. 45. Any Shameful Comments? Refactor!
  46. 46. ! ! DOCUMENTATION CODE is 2
  47. 47. Word Cloud 3
  48. 48. 56 What  is  this   app  about?
  49. 49. You  do  it  wrong!
  50. 50. Word Cloud: dispatching + Discuss
  51. 51. Word Cloud: fuel card monitoring + Compare
  52. 52. LIVING GLOSSARY 4
  53. 53. How do I represent the Ubiquitous Language in practice?
  54. 54. Annotate domain-relevant classes Source code as reference
  55. 55. Living Glossary Living Glossary Processor Source Code & Annotations Living Glossary always up-to-date
  56. 56. Run the Living Glossary
  57. 57. Custom Doclet to export Living Glossary
  58. 58. Bounded Context comment
  59. 59. Core Concepts
  60. 60. Class comment
  61. 61. ANOTHER EXAMPLE Sent directly to end customers every week
  62. 62. Run the Living Glossary Make changes to the code rename move to /infra remove annotations change comments
  63. 63. KNOWLEDGE AUGMENTATION
  64. 64. Code
  65. 65. Bounded Contexts are there
  66. 66. Bounded Contexts are there Implicitly
  67. 67. Annotations
  68. 68. Bounded Contexts
  69. 69. Embedded Learning
  70. 70. Embedded Learning
  71. 71. Embedded Learning
  72. 72. Embedded Learning
  73. 73. Embedded Learning Learn on the job
  74. 74. LIVING DIAGRAM 4
  75. 75. Run the Living Diagram
  76. 76. Living Diagram Living Diagram Processor Source Code Living Diagram always up-to-date
  77. 77. Run the Living Diagram Make changes to the code Run the Living Diagram
  78. 78. Example: Hexagonal Architecture
  79. 79. Domain Model inside Infrastructure Outside
  80. 80. Design is already there
  81. 81. Design is already there Implicitly
  82. 82. Just rely on documented naming conventions
  83. 83. *.domain! *.infra! NOT *Test
  84. 84. Living Diagram Living Diagram Processor Source Code Living Diagram always up-to-date
  85. 85. 95 tada!
  86. 86. CONTENT FILTERING (CURATION) is KEY
  87. 87. No Value
  88. 88. 1 Diagram 1 Purpose
  89. 89. Example: Hexagonal Architecture
  90. 90. Fix the code Run the Living Diagram
  91. 91. OOPS!
  92. 92. Reality Check
  93. 93. https://www.structurizr.com/ by Simon Brown
  94. 94. https://www.structurizr.com/
  95. 95. LISTEN TO THE DOCUMENTATION FRUSTRATIONS
  96. 96. Hard to do the Living Glossary? A signal!
  97. 97. Hard to do the Living Diagrams? A signal!
  98. 98. Programming by Coincidence
  99. 99. Know what you’re doing -> Already half-documented
  100. 100. ANYBODY CAN ! APPRECIATE! IT’S A MESS
  101. 101. PRESSURE TO ! IMPROVE DESIGN
  102. 102. Simpler Design Less documentation needed
  103. 103. More standard Less documentation needed ! fogus @fogus
  104. 104. Fix your workflow Write code Write tests Write doc Write tests = write doc Write code = write doc From Mikko Ohtamaa
  105. 105. COOL!
  106. 106. In Closing
  107. 107. https://leanpub.com/livingdocumentation BUY MY BOOK!
  108. 108. Boring Documentation is dead Long Live Living Documentation!
  109. 109. Not about particular techniques ! Reconsider dealing with the knowledge
  110. 110. Share Your Ideas & Experiments
  111. 111. Questions? Did you try similar things too? Let’s discuss! @cyriux
  112. 112. Follow me @cyriux ! Slides: slideshare.net/cyriux Blog: cyrille.martraire.com ! In Paris? Join !
  113. 113. Merci

×