Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Leaving Documentation, or Living Documentation?

Leaving Documentation, or Living Documentation?

Some knowledge is worth sharing to accelerate the work of teams and to improve the quality of the result. Remote work only makes this concern more obvious. But the traditional techniques of documentation suffer from notorious flaws that make them unfit for modern, fast-paced delivery approaches.

It’s time to leave documentation, and to fully embrace a Living Documentation perspective instead, as a set of lightweight knowledge sharing practices that are effective in continuously changing environments.

Cyrille, the author of the book Living Documentation (Addison-Wesley Professionals) will be your guide, so that you’ll never see documentation the same way again!

Conference "The Legacy of Socrates" 7th edition, video also online: https://www.youtube.com/watch?v=icGhEOWPqB4

Cyrille Martraire

September 22, 2021
Tweet

More Decks by Cyrille Martraire

Other Decks in Programming

Transcript

  1. 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
  2. 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
  3. THE IDEAL Having access to just enough knowledge, just in

    time, that you can trust, is a driver to accelerate software delivery
  4. 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
  5. 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
  6. - 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!
  7. 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…)
  8. Living Glossary Living Glossary Processor Source Code & Annotations Living

    Glossary always up-to-date Add Delete rename move always in sync!
  9. 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)
  10. Create your own annotation(s) @Layer(name=””) @HexagonalArchitecture @ViewModel @DomainModel @Notification @Collaborator

    @ComponentRoot @Adapter(from = …, to = …) @MainStyle(style=””) @Rationale(””)
  11. Enforced Guidelines Why have people go look for the knowledge

    when the knowledge could prompt them at the right time instead?
  12. Enforced Guidelines Why have people go look for the knowledge

    when the knowledge could prompt them at the right time instead?
  13. *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
  14. *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
  15. Stable or Volatile? ”This module follows an FP-style to reduce

    errors and ensure it is highly testable.”
  16. New Claim Management as Single Source of Truth until the

    claim is accepted by the customer Accepted on 01/12/2015 Context We want avoid confusion arising from unclear authority of data, which consumes developer time to fix 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. Decision 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).
  17. … Consequences Given the legacy background, it is unfortunately necessary

    for some time to have a different Golden Source across the life of a claim. Still, at any point in the life of the claim, the authoritative data are clearly in one single source. This should be re-considered to move to one constant single source whenever possible. Because of that discrepancy, before the push: commands to create or update a claim are sent to Claim Management, with events sent around and in particular to LCM to sync the LCM data (Legacy claim mainframe as a Read Model). After the push: remote calls to LCM are used to update the claim in LCM, with events sent back to Claim Management to sync it (Claim Management as a Read Model).
  18. … Consequences Given the legacy background, it is unfortunately necessary

    for some time to have a different Golden Source across the life of a claim. Still, at any point in the life of the claim, the authoritative data are clearly in one single source. This should be re-considered to move to one constant single source whenever possible. Because of that discrepancy, before the push: commands to create or update a claim are sent to Claim Management, with events sent around and in particular to LCM to sync the LCM data (Legacy claim mainframe as a Read Model). After the push: remote calls to LCM are used to update the claim in LCM, with events sent back to Claim Management to sync it (Claim Management as a Read Model). FEEL FREE TO CHANGE THAT ONCE AS SOON AS IT’S POSSIBLE!
  19. 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
  20. 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
  21. Highlight Exemplary areas of code because developers often get ”inspiration”

    from existing code somewhere else in the application Find Usages: @Exemplary
  22. IDE as Integrated Documentation Why document by hand what your

    IDE can instantly answer on-demand? Find Usages: @Exemplary
  23. Data Governance/Lineage On any DAO, mark the stored objects with

    their authority: @GoldenSource(”Product”) @GoldenCopy(”Customer”, rationale = ”AutonomyOverAuthority”, refresh = ”events from RabbitMQ”)
  24. Augmented Code, with Metadata Github topics Consul tags Class /

    Package annotations Manifest at root of Repository Domains: - Credit Initiation - Credit Approval GoldenSource: - Request - Decisions @DomainModel package my.domain { … Zipkin annotations
  25. - 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!