SlideShare a Scribd company logo
1 of 15
Download to read offline
LIVING DOCUMENTATION
Mini-workshop
https://leanpub.com/livingdocumentation
Cyrille Marraine
“When comes the time to do documentation,
members of the team select some elements of
knowledge of what has been done and perform a
Manual Transcription.
“The documentation quickly becomes obsolete, and
you end up with an incomplete documentation
that you cannot trust.
FROM THE “MANIFESTO FOR AGILE SOFTWARE DEVELOPMENT ”
We are uncovering better ways of developing software by doing
it and helping others do it. Through this work we have come to
value:
➤ Working software over comprehensive documentation
http://agilemanifesto.org/
“Each instruction typed in a programming language
is a decision.
PRINCIPLES
➤ Knowledge that is of interest for a long period of
time deserves to be documented.
➤ Knowledge that is of interest to a large number of
people deserves to be documented.
➤ Knowledge that is valuable or critical may also need
to be documented.
“The best place to store documentation is on the
documented thing itself.
“In a software project most of the knowledge is
present in some form somewhere in the artefacts.
EXAMPLES
➤ Self-documenting code and Clean Code practices, including:
➤ Class and method naming
➤ Types
➤ Annotations that add knowledge to elements of the
programming language
➤ Javadoc comments on public interfaces, classes and main
methods
➤ Folder organization, modules and submodules
decomposition and naming
“The key concern to keep in mind is the cost of
evolution and maintenance of the documentation.
Living documentation mini-workshop
PRINCIPLES OF LIVING DOCUMENTATION
➤ Reliable
➤ Low-Effort
➤ Collaborative
➤ Insightful
“If it’s not fun, you’ll not want to do it so often and
the practice will progressively disappear.
LET THE WORKSHOP BEGIN!
➤ Explore living documentation practices, for example in:
➤ “Part 2: Living documentation” of the book, or
➤ README.md of the sandbox project
➤ Try to implement/automate something as a Proof-of-Concept
➤ Do the most simple thing to make it work
➤ Homework: make it nice & reusable :)

More Related Content

Similar to Living documentation mini-workshop

Technical Writing Overview: WTD Nigeria
Technical Writing Overview: WTD NigeriaTechnical Writing Overview: WTD Nigeria
Technical Writing Overview: WTD NigeriaMargaret Fero
 
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The QuestionJDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The QuestionPROIDEA
 
5 Must-to-Read Books on DevOps
5 Must-to-Read Books on DevOps5 Must-to-Read Books on DevOps
5 Must-to-Read Books on DevOpsGanesh Samarthyam
 
The Art Of Documentation for Open Source Projects
The Art Of Documentation for Open Source ProjectsThe Art Of Documentation for Open Source Projects
The Art Of Documentation for Open Source ProjectsBen Hall
 
Agile Software Development
Agile Software DevelopmentAgile Software Development
Agile Software DevelopmentAhmet Bulut
 
Importance of Documentation for programmers
Importance of Documentation for programmers Importance of Documentation for programmers
Importance of Documentation for programmers NASSCOM
 
Managing a Project the Drupal Way - Drupal Open Days Ireland
Managing a Project the Drupal Way - Drupal Open Days IrelandManaging a Project the Drupal Way - Drupal Open Days Ireland
Managing a Project the Drupal Way - Drupal Open Days IrelandEmma Jane Hogbin Westby
 
NLJUG speaker academy 2022 - session 1
NLJUG speaker academy 2022 - session 1NLJUG speaker academy 2022 - session 1
NLJUG speaker academy 2022 - session 1Bert Jan Schrijver
 
DevRel Salon - Writing Decent Documentation, a learning journey with plenty o...
DevRel Salon - Writing Decent Documentation, a learning journey with plenty o...DevRel Salon - Writing Decent Documentation, a learning journey with plenty o...
DevRel Salon - Writing Decent Documentation, a learning journey with plenty o...Abdelhalim DADOUCHE
 
Lean collaborative test plans
Lean collaborative test plansLean collaborative test plans
Lean collaborative test plansDani Nordin
 
UX Design With Distributed Teams
UX Design With Distributed TeamsUX Design With Distributed Teams
UX Design With Distributed TeamsJohannes Baeck
 
Usa prácticas de integración continua y sobrevive para luchar otro día.
 Usa prácticas de integración continua y sobrevive para luchar otro día. Usa prácticas de integración continua y sobrevive para luchar otro día.
Usa prácticas de integración continua y sobrevive para luchar otro día.Software Guru
 
NLJUG speaker academy 2023 - session 1
NLJUG speaker academy 2023 - session 1NLJUG speaker academy 2023 - session 1
NLJUG speaker academy 2023 - session 1Bert Jan Schrijver
 
Sprinting to Success: Why Agile and DITA Work So Well Together
Sprinting to Success: Why Agile and DITA Work So Well TogetherSprinting to Success: Why Agile and DITA Work So Well Together
Sprinting to Success: Why Agile and DITA Work So Well TogetherIXIASOFT
 
Writing documentation with neurodivergent oss contributors in mind (1)
Writing documentation with neurodivergent oss contributors in mind (1)Writing documentation with neurodivergent oss contributors in mind (1)
Writing documentation with neurodivergent oss contributors in mind (1)Rin Oliver (they/them)
 
Agile Content Development
Agile Content DevelopmentAgile Content Development
Agile Content DevelopmentDave Derrick
 

Similar to Living documentation mini-workshop (20)

The Road to DITA
The Road to DITAThe Road to DITA
The Road to DITA
 
Technical Writing Overview: WTD Nigeria
Technical Writing Overview: WTD NigeriaTechnical Writing Overview: WTD Nigeria
Technical Writing Overview: WTD Nigeria
 
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The QuestionJDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
 
5 Must-to-Read Books on DevOps
5 Must-to-Read Books on DevOps5 Must-to-Read Books on DevOps
5 Must-to-Read Books on DevOps
 
The Art Of Documentation for Open Source Projects
The Art Of Documentation for Open Source ProjectsThe Art Of Documentation for Open Source Projects
The Art Of Documentation for Open Source Projects
 
Agile Software Development
Agile Software DevelopmentAgile Software Development
Agile Software Development
 
Importance of Documentation for programmers
Importance of Documentation for programmers Importance of Documentation for programmers
Importance of Documentation for programmers
 
Managing a Project the Drupal Way - Drupal Open Days Ireland
Managing a Project the Drupal Way - Drupal Open Days IrelandManaging a Project the Drupal Way - Drupal Open Days Ireland
Managing a Project the Drupal Way - Drupal Open Days Ireland
 
NLJUG speaker academy 2022 - session 1
NLJUG speaker academy 2022 - session 1NLJUG speaker academy 2022 - session 1
NLJUG speaker academy 2022 - session 1
 
It's XP, Stupid
It's XP, StupidIt's XP, Stupid
It's XP, Stupid
 
DevRel Salon - Writing Decent Documentation, a learning journey with plenty o...
DevRel Salon - Writing Decent Documentation, a learning journey with plenty o...DevRel Salon - Writing Decent Documentation, a learning journey with plenty o...
DevRel Salon - Writing Decent Documentation, a learning journey with plenty o...
 
Lean collaborative test plans
Lean collaborative test plansLean collaborative test plans
Lean collaborative test plans
 
UX Design With Distributed Teams
UX Design With Distributed TeamsUX Design With Distributed Teams
UX Design With Distributed Teams
 
Usa prácticas de integración continua y sobrevive para luchar otro día.
 Usa prácticas de integración continua y sobrevive para luchar otro día. Usa prácticas de integración continua y sobrevive para luchar otro día.
Usa prácticas de integración continua y sobrevive para luchar otro día.
 
Scrum in-a-flash
Scrum in-a-flashScrum in-a-flash
Scrum in-a-flash
 
NLJUG speaker academy 2023 - session 1
NLJUG speaker academy 2023 - session 1NLJUG speaker academy 2023 - session 1
NLJUG speaker academy 2023 - session 1
 
Sprinting to Success: Why Agile and DITA Work So Well Together
Sprinting to Success: Why Agile and DITA Work So Well TogetherSprinting to Success: Why Agile and DITA Work So Well Together
Sprinting to Success: Why Agile and DITA Work So Well Together
 
Writing documentation with neurodivergent oss contributors in mind (1)
Writing documentation with neurodivergent oss contributors in mind (1)Writing documentation with neurodivergent oss contributors in mind (1)
Writing documentation with neurodivergent oss contributors in mind (1)
 
Agile Content Development
Agile Content DevelopmentAgile Content Development
Agile Content Development
 
Agile presentation
Agile presentationAgile presentation
Agile presentation
 

More from Matthias Noback

Rector fireside chat - PHPMiNDS meetup
Rector fireside chat - PHPMiNDS meetupRector fireside chat - PHPMiNDS meetup
Rector fireside chat - PHPMiNDS meetupMatthias Noback
 
Service abstractions - Part 1: Queries
Service abstractions - Part 1: QueriesService abstractions - Part 1: Queries
Service abstractions - Part 1: QueriesMatthias Noback
 
Hexagonal Symfony - SymfonyCon Amsterdam 2019
Hexagonal Symfony - SymfonyCon Amsterdam 2019Hexagonal Symfony - SymfonyCon Amsterdam 2019
Hexagonal Symfony - SymfonyCon Amsterdam 2019Matthias Noback
 
Advanced web application architecture - PHP Barcelona
Advanced web application architecture  - PHP BarcelonaAdvanced web application architecture  - PHP Barcelona
Advanced web application architecture - PHP BarcelonaMatthias Noback
 
A testing strategy for hexagonal applications
A testing strategy for hexagonal applicationsA testing strategy for hexagonal applications
A testing strategy for hexagonal applicationsMatthias Noback
 
Advanced web application architecture - Talk
Advanced web application architecture - TalkAdvanced web application architecture - Talk
Advanced web application architecture - TalkMatthias Noback
 
DPC 2019, Amsterdam: Beyond design patterns and principles - writing good OO ...
DPC 2019, Amsterdam: Beyond design patterns and principles - writing good OO ...DPC 2019, Amsterdam: Beyond design patterns and principles - writing good OO ...
DPC 2019, Amsterdam: Beyond design patterns and principles - writing good OO ...Matthias Noback
 
Layers, ports and adapters
Layers, ports and adaptersLayers, ports and adapters
Layers, ports and adaptersMatthias Noback
 
Beyond design principles and patterns (muCon 2019 edition)
Beyond design principles and patterns (muCon 2019 edition)Beyond design principles and patterns (muCon 2019 edition)
Beyond design principles and patterns (muCon 2019 edition)Matthias Noback
 
Brutal refactoring, lying code, the Churn, and other emotional stories from L...
Brutal refactoring, lying code, the Churn, and other emotional stories from L...Brutal refactoring, lying code, the Churn, and other emotional stories from L...
Brutal refactoring, lying code, the Churn, and other emotional stories from L...Matthias Noback
 
Advanced web application architecture Way2Web
Advanced web application architecture Way2WebAdvanced web application architecture Way2Web
Advanced web application architecture Way2WebMatthias Noback
 
Brutal refactoring, lying code, the Churn, and other emotional stories from L...
Brutal refactoring, lying code, the Churn, and other emotional stories from L...Brutal refactoring, lying code, the Churn, and other emotional stories from L...
Brutal refactoring, lying code, the Churn, and other emotional stories from L...Matthias Noback
 
Beyond Design Principles and Patterns
Beyond Design Principles and PatternsBeyond Design Principles and Patterns
Beyond Design Principles and PatternsMatthias Noback
 
Building Autonomous Services
Building Autonomous ServicesBuilding Autonomous Services
Building Autonomous ServicesMatthias Noback
 
Advanced Application Architecture Symfony Live Berlin 2018
Advanced Application Architecture Symfony Live Berlin 2018Advanced Application Architecture Symfony Live Berlin 2018
Advanced Application Architecture Symfony Live Berlin 2018Matthias Noback
 
Building autonomous services
Building autonomous servicesBuilding autonomous services
Building autonomous servicesMatthias Noback
 

More from Matthias Noback (20)

Rector fireside chat - PHPMiNDS meetup
Rector fireside chat - PHPMiNDS meetupRector fireside chat - PHPMiNDS meetup
Rector fireside chat - PHPMiNDS meetup
 
Service abstractions - Part 1: Queries
Service abstractions - Part 1: QueriesService abstractions - Part 1: Queries
Service abstractions - Part 1: Queries
 
Hexagonal Symfony - SymfonyCon Amsterdam 2019
Hexagonal Symfony - SymfonyCon Amsterdam 2019Hexagonal Symfony - SymfonyCon Amsterdam 2019
Hexagonal Symfony - SymfonyCon Amsterdam 2019
 
Advanced web application architecture - PHP Barcelona
Advanced web application architecture  - PHP BarcelonaAdvanced web application architecture  - PHP Barcelona
Advanced web application architecture - PHP Barcelona
 
A testing strategy for hexagonal applications
A testing strategy for hexagonal applicationsA testing strategy for hexagonal applications
A testing strategy for hexagonal applications
 
Advanced web application architecture - Talk
Advanced web application architecture - TalkAdvanced web application architecture - Talk
Advanced web application architecture - Talk
 
DPC 2019, Amsterdam: Beyond design patterns and principles - writing good OO ...
DPC 2019, Amsterdam: Beyond design patterns and principles - writing good OO ...DPC 2019, Amsterdam: Beyond design patterns and principles - writing good OO ...
DPC 2019, Amsterdam: Beyond design patterns and principles - writing good OO ...
 
Layers, ports and adapters
Layers, ports and adaptersLayers, ports and adapters
Layers, ports and adapters
 
Beyond design principles and patterns (muCon 2019 edition)
Beyond design principles and patterns (muCon 2019 edition)Beyond design principles and patterns (muCon 2019 edition)
Beyond design principles and patterns (muCon 2019 edition)
 
Brutal refactoring, lying code, the Churn, and other emotional stories from L...
Brutal refactoring, lying code, the Churn, and other emotional stories from L...Brutal refactoring, lying code, the Churn, and other emotional stories from L...
Brutal refactoring, lying code, the Churn, and other emotional stories from L...
 
Advanced web application architecture Way2Web
Advanced web application architecture Way2WebAdvanced web application architecture Way2Web
Advanced web application architecture Way2Web
 
Brutal refactoring, lying code, the Churn, and other emotional stories from L...
Brutal refactoring, lying code, the Churn, and other emotional stories from L...Brutal refactoring, lying code, the Churn, and other emotional stories from L...
Brutal refactoring, lying code, the Churn, and other emotional stories from L...
 
Beyond Design Principles and Patterns
Beyond Design Principles and PatternsBeyond Design Principles and Patterns
Beyond Design Principles and Patterns
 
Building Autonomous Services
Building Autonomous ServicesBuilding Autonomous Services
Building Autonomous Services
 
Advanced Application Architecture Symfony Live Berlin 2018
Advanced Application Architecture Symfony Live Berlin 2018Advanced Application Architecture Symfony Live Berlin 2018
Advanced Application Architecture Symfony Live Berlin 2018
 
Designing for Autonomy
Designing for AutonomyDesigning for Autonomy
Designing for Autonomy
 
Docker workshop
Docker workshopDocker workshop
Docker workshop
 
Docker swarm workshop
Docker swarm workshopDocker swarm workshop
Docker swarm workshop
 
Docker compose workshop
Docker compose workshopDocker compose workshop
Docker compose workshop
 
Building autonomous services
Building autonomous servicesBuilding autonomous services
Building autonomous services
 

Recently uploaded

Sales Territory Management: A Definitive Guide to Expand Sales Coverage
Sales Territory Management: A Definitive Guide to Expand Sales CoverageSales Territory Management: A Definitive Guide to Expand Sales Coverage
Sales Territory Management: A Definitive Guide to Expand Sales CoverageDista
 
Deep Learning for Images with PyTorch - Datacamp
Deep Learning for Images with PyTorch - DatacampDeep Learning for Images with PyTorch - Datacamp
Deep Learning for Images with PyTorch - DatacampVICTOR MAESTRE RAMIREZ
 
Webinar_050417_LeClair12345666777889.ppt
Webinar_050417_LeClair12345666777889.pptWebinar_050417_LeClair12345666777889.ppt
Webinar_050417_LeClair12345666777889.pptkinjal48
 
OpenChain Webinar: Universal CVSS Calculator
OpenChain Webinar: Universal CVSS CalculatorOpenChain Webinar: Universal CVSS Calculator
OpenChain Webinar: Universal CVSS CalculatorShane Coughlan
 
Introduction-to-Software-Development-Outsourcing.pptx
Introduction-to-Software-Development-Outsourcing.pptxIntroduction-to-Software-Development-Outsourcing.pptx
Introduction-to-Software-Development-Outsourcing.pptxIntelliSource Technologies
 
online pdf editor software solutions.pdf
online pdf editor software solutions.pdfonline pdf editor software solutions.pdf
online pdf editor software solutions.pdfMeon Technology
 
AI Embracing Every Shade of Human Beauty
AI Embracing Every Shade of Human BeautyAI Embracing Every Shade of Human Beauty
AI Embracing Every Shade of Human BeautyRaymond Okyere-Forson
 
JS-Experts - Cybersecurity for Generative AI
JS-Experts - Cybersecurity for Generative AIJS-Experts - Cybersecurity for Generative AI
JS-Experts - Cybersecurity for Generative AIIvo Andreev
 
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.Sharon Liu
 
Enterprise Document Management System - Qualityze Inc
Enterprise Document Management System - Qualityze IncEnterprise Document Management System - Qualityze Inc
Enterprise Document Management System - Qualityze Incrobinwilliams8624
 
Big Data Bellevue Meetup | Enhancing Python Data Loading in the Cloud for AI/ML
Big Data Bellevue Meetup | Enhancing Python Data Loading in the Cloud for AI/MLBig Data Bellevue Meetup | Enhancing Python Data Loading in the Cloud for AI/ML
Big Data Bellevue Meetup | Enhancing Python Data Loading in the Cloud for AI/MLAlluxio, Inc.
 
Top Software Development Trends in 2024
Top Software Development Trends in  2024Top Software Development Trends in  2024
Top Software Development Trends in 2024Mind IT Systems
 
Streamlining Your Application Builds with Cloud Native Buildpacks
Streamlining Your Application Builds  with Cloud Native BuildpacksStreamlining Your Application Builds  with Cloud Native Buildpacks
Streamlining Your Application Builds with Cloud Native BuildpacksVish Abrams
 
Growing Oxen: channel operators and retries
Growing Oxen: channel operators and retriesGrowing Oxen: channel operators and retries
Growing Oxen: channel operators and retriesSoftwareMill
 
How Does the Epitome of Spyware Differ from Other Malicious Software?
How Does the Epitome of Spyware Differ from Other Malicious Software?How Does the Epitome of Spyware Differ from Other Malicious Software?
How Does the Epitome of Spyware Differ from Other Malicious Software?AmeliaSmith90
 
ARM Talk @ Rejekts - Will ARM be the new Mainstream in our Data Centers_.pdf
ARM Talk @ Rejekts - Will ARM be the new Mainstream in our Data Centers_.pdfARM Talk @ Rejekts - Will ARM be the new Mainstream in our Data Centers_.pdf
ARM Talk @ Rejekts - Will ARM be the new Mainstream in our Data Centers_.pdfTobias Schneck
 
Watermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security ChallengesWatermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security ChallengesShyamsundar Das
 
Transforming PMO Success with AI - Discover OnePlan Strategic Portfolio Work ...
Transforming PMO Success with AI - Discover OnePlan Strategic Portfolio Work ...Transforming PMO Success with AI - Discover OnePlan Strategic Portfolio Work ...
Transforming PMO Success with AI - Discover OnePlan Strategic Portfolio Work ...OnePlan Solutions
 
Cybersecurity Challenges with Generative AI - for Good and Bad
Cybersecurity Challenges with Generative AI - for Good and BadCybersecurity Challenges with Generative AI - for Good and Bad
Cybersecurity Challenges with Generative AI - for Good and BadIvo Andreev
 

Recently uploaded (20)

Salesforce AI Associate Certification.pptx
Salesforce AI Associate Certification.pptxSalesforce AI Associate Certification.pptx
Salesforce AI Associate Certification.pptx
 
Sales Territory Management: A Definitive Guide to Expand Sales Coverage
Sales Territory Management: A Definitive Guide to Expand Sales CoverageSales Territory Management: A Definitive Guide to Expand Sales Coverage
Sales Territory Management: A Definitive Guide to Expand Sales Coverage
 
Deep Learning for Images with PyTorch - Datacamp
Deep Learning for Images with PyTorch - DatacampDeep Learning for Images with PyTorch - Datacamp
Deep Learning for Images with PyTorch - Datacamp
 
Webinar_050417_LeClair12345666777889.ppt
Webinar_050417_LeClair12345666777889.pptWebinar_050417_LeClair12345666777889.ppt
Webinar_050417_LeClair12345666777889.ppt
 
OpenChain Webinar: Universal CVSS Calculator
OpenChain Webinar: Universal CVSS CalculatorOpenChain Webinar: Universal CVSS Calculator
OpenChain Webinar: Universal CVSS Calculator
 
Introduction-to-Software-Development-Outsourcing.pptx
Introduction-to-Software-Development-Outsourcing.pptxIntroduction-to-Software-Development-Outsourcing.pptx
Introduction-to-Software-Development-Outsourcing.pptx
 
online pdf editor software solutions.pdf
online pdf editor software solutions.pdfonline pdf editor software solutions.pdf
online pdf editor software solutions.pdf
 
AI Embracing Every Shade of Human Beauty
AI Embracing Every Shade of Human BeautyAI Embracing Every Shade of Human Beauty
AI Embracing Every Shade of Human Beauty
 
JS-Experts - Cybersecurity for Generative AI
JS-Experts - Cybersecurity for Generative AIJS-Experts - Cybersecurity for Generative AI
JS-Experts - Cybersecurity for Generative AI
 
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.
 
Enterprise Document Management System - Qualityze Inc
Enterprise Document Management System - Qualityze IncEnterprise Document Management System - Qualityze Inc
Enterprise Document Management System - Qualityze Inc
 
Big Data Bellevue Meetup | Enhancing Python Data Loading in the Cloud for AI/ML
Big Data Bellevue Meetup | Enhancing Python Data Loading in the Cloud for AI/MLBig Data Bellevue Meetup | Enhancing Python Data Loading in the Cloud for AI/ML
Big Data Bellevue Meetup | Enhancing Python Data Loading in the Cloud for AI/ML
 
Top Software Development Trends in 2024
Top Software Development Trends in  2024Top Software Development Trends in  2024
Top Software Development Trends in 2024
 
Streamlining Your Application Builds with Cloud Native Buildpacks
Streamlining Your Application Builds  with Cloud Native BuildpacksStreamlining Your Application Builds  with Cloud Native Buildpacks
Streamlining Your Application Builds with Cloud Native Buildpacks
 
Growing Oxen: channel operators and retries
Growing Oxen: channel operators and retriesGrowing Oxen: channel operators and retries
Growing Oxen: channel operators and retries
 
How Does the Epitome of Spyware Differ from Other Malicious Software?
How Does the Epitome of Spyware Differ from Other Malicious Software?How Does the Epitome of Spyware Differ from Other Malicious Software?
How Does the Epitome of Spyware Differ from Other Malicious Software?
 
ARM Talk @ Rejekts - Will ARM be the new Mainstream in our Data Centers_.pdf
ARM Talk @ Rejekts - Will ARM be the new Mainstream in our Data Centers_.pdfARM Talk @ Rejekts - Will ARM be the new Mainstream in our Data Centers_.pdf
ARM Talk @ Rejekts - Will ARM be the new Mainstream in our Data Centers_.pdf
 
Watermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security ChallengesWatermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security Challenges
 
Transforming PMO Success with AI - Discover OnePlan Strategic Portfolio Work ...
Transforming PMO Success with AI - Discover OnePlan Strategic Portfolio Work ...Transforming PMO Success with AI - Discover OnePlan Strategic Portfolio Work ...
Transforming PMO Success with AI - Discover OnePlan Strategic Portfolio Work ...
 
Cybersecurity Challenges with Generative AI - for Good and Bad
Cybersecurity Challenges with Generative AI - for Good and BadCybersecurity Challenges with Generative AI - for Good and Bad
Cybersecurity Challenges with Generative AI - for Good and Bad
 

Living documentation mini-workshop

  • 3. “When comes the time to do documentation, members of the team select some elements of knowledge of what has been done and perform a Manual Transcription.
  • 4. “The documentation quickly becomes obsolete, and you end up with an incomplete documentation that you cannot trust.
  • 5. FROM THE “MANIFESTO FOR AGILE SOFTWARE DEVELOPMENT ” We are uncovering better ways of developing software by doing it and helping others do it. Through this work we have come to value: ➤ Working software over comprehensive documentation http://agilemanifesto.org/
  • 6. “Each instruction typed in a programming language is a decision.
  • 7. PRINCIPLES ➤ Knowledge that is of interest for a long period of time deserves to be documented. ➤ Knowledge that is of interest to a large number of people deserves to be documented. ➤ Knowledge that is valuable or critical may also need to be documented.
  • 8. “The best place to store documentation is on the documented thing itself.
  • 9. “In a software project most of the knowledge is present in some form somewhere in the artefacts.
  • 10. EXAMPLES ➤ Self-documenting code and Clean Code practices, including: ➤ Class and method naming ➤ Types ➤ Annotations that add knowledge to elements of the programming language ➤ Javadoc comments on public interfaces, classes and main methods ➤ Folder organization, modules and submodules decomposition and naming
  • 11. “The key concern to keep in mind is the cost of evolution and maintenance of the documentation.
  • 13. PRINCIPLES OF LIVING DOCUMENTATION ➤ Reliable ➤ Low-Effort ➤ Collaborative ➤ Insightful
  • 14. “If it’s not fun, you’ll not want to do it so often and the practice will progressively disappear.
  • 15. LET THE WORKSHOP BEGIN! ➤ Explore living documentation practices, for example in: ➤ “Part 2: Living documentation” of the book, or ➤ README.md of the sandbox project ➤ Try to implement/automate something as a Proof-of-Concept ➤ Do the most simple thing to make it work ➤ Homework: make it nice & reusable :)