SlideShare una empresa de Scribd logo
1 de 106
Descargar para leer sin conexión
LIVING
DOCUMENTATION
@samuelroze - 2020
While the audience of this talk is technical
people, it is almost non technical.
It's aim is to give you (hopefully new) insights
about what documentation is and can be,
gathered from experience and this great book.
@samuelroze - 2020
WHICH DOCUMENTATION ARE WE TALKING ABOUT?
@samuelroze - 2020
WHICH DOCUMENTATION ARE WE TALKING ABOUT?
▸Internal. The audience is the project's members and
direct stakeholders. The aim is to explain intricacies
of the concepts, decisions, architecture and (little
bit) how the product behaves.
@samuelroze - 2020
WHICH DOCUMENTATION ARE WE TALKING ABOUT?
▸Internal. The audience is the project's members and
direct stakeholders. The aim is to explain intricacies
of the concepts, decisions, architecture and (little
bit) how the product behaves.
▸External. The audience is the project's customers. It's
mostly about how to use it and a how it behaves.
@samuelroze - 2020
WHAT IS (INTERNAL)
DOCUMENTATION USEFUL
FOR?
@samuelroze - 2020
REDUCING WASTED TIME!
@samuelroze - 2020
DOCUMENTATION CAN HELP WITH... (1/3)
@samuelroze - 2020
DOCUMENTATION CAN HELP WITH... (1/3)
▸Reducing technical debt. Usually, tech debt is because an
engineer or a team didn't have all the context they
needed to have.
@samuelroze - 2020
DOCUMENTATION CAN HELP WITH... (1/3)
▸Reducing technical debt. Usually, tech debt is because an
engineer or a team didn't have all the context they
needed to have.
▸
!
"Outdated or lacking documentation is a
considerable contributor to increased costs of
software systems maintenance" - Yulia Sh. et al. [1]
@samuelroze - 2020
DOCUMENTATION CAN HELP WITH... (2/3)
@samuelroze - 2020
DOCUMENTATION CAN HELP WITH... (2/3)
▸On-boarding new engineers. As a company scales, on-boarding
engineers can be a huge amount of effort without
good documentation.
@samuelroze - 2020
DOCUMENTATION CAN HELP WITH... (2/3)
▸On-boarding new engineers. As a company scales, on-boarding
engineers can be a huge amount of effort without
good documentation.
▸
!
Overall, we are pretty bad at communicating
context and getting people onboarded [2]
@samuelroze - 2020
DOCUMENTATION CAN HELP WITH... (3/3)
Conversations. By reducing the amount of mis-
understanding thanks to a clear common vocabulary
(ubiquitous language) and reducing un-necessary
interruptions because knowledge is easily accessible.
!
Flags “What do you mean by X?”. "Is the field X
synchronised?" "What time 'Morning' starts and
ends?" ...
@samuelroze - 2020
Cost of translation reminder.
@samuelroze - 2020
SOUNDS FABULOUS...
WHAT'S WRONG WITH OUR CURRENT
DOCUMENTATIONS?
@samuelroze - 2020
@samuelroze - 2020
▸ What to document is unclear. We sometimes are overloaded with
information which either is known by everybody or is not relevant.
@samuelroze - 2020
▸ What to document is unclear. We sometimes are overloaded with
information which either is known by everybody or is not relevant.
▸ Out of date. You know when reading a documentation that you need
to check the date at which is was written...
@samuelroze - 2020
▸ What to document is unclear. We sometimes are overloaded with
information which either is known by everybody or is not relevant.
▸ Out of date. You know when reading a documentation that you need
to check the date at which is was written...
▸ Boring. It's usually not a great experience to go and... RTFM. (i.e. flat
& ugly files/slides)
@samuelroze - 2020
4 PRINCIPLES OF A LIVING DOCUMENTATION
@samuelroze - 2020
4 PRINCIPLES OF A LIVING DOCUMENTATION
1. Reliable. You don't worry about the version.
@samuelroze - 2020
4 PRINCIPLES OF A LIVING DOCUMENTATION
1. Reliable. You don't worry about the version.
2. Low effort. Simple to read & simple to maintain.
@samuelroze - 2020
4 PRINCIPLES OF A LIVING DOCUMENTATION
1. Reliable. You don't worry about the version.
2. Low effort. Simple to read & simple to maintain.
3. Collaborative. Communication first, "sediment" knowledge later.
@samuelroze - 2020
4 PRINCIPLES OF A LIVING DOCUMENTATION
1. Reliable. You don't worry about the version.
2. Low effort. Simple to read & simple to maintain.
3. Collaborative. Communication first, "sediment" knowledge later.
4. Insightful. Explicit decisions, things that are not that good, or yet
unknowns.
@samuelroze - 2020
WHAT SHOULD YOU DOCUMENT?
@samuelroze - 2020
WHAT SHOULD YOU DOCUMENT?
1. Generic knowledge. How is Symfony working, how to run an
SQL query, what is Kafka about, how to use
GitHub, ...
@samuelroze - 2020
WHAT SHOULD YOU DOCUMENT?
1. Generic knowledge. How is Symfony working, how to run an
SQL query, what is Kafka about, how to use
GitHub, ...
2. Specific knowledge. Your architecture, decisions you took
so far, details about your industry, ...
@samuelroze - 2020
WHAT SHOULD YOU DOCUMENT?
1. Generic knowledge. How is Symfony working, how to run an
SQL query, what is Kafka about, how to use
GitHub, ...
2. Specific knowledge. Your architecture, decisions you took
so far, details about your industry, ...
▸
✋
In shot, focus only here.
@samuelroze - 2020
HOW DO YOU ENSURE 'FRESHNESS'?
@samuelroze - 2020
HOW DO YOU ENSURE 'FRESHNESS'?
▸
!
The knowledge already exists. You have authoritative sources of
knowledge (i.e. source of truth). It is likely to be your
source code but it can be somewhere else (databases,
documents, ...).
@samuelroze - 2020
HOW DO YOU ENSURE 'FRESHNESS'?
▸
!
The knowledge already exists. You have authoritative sources of
knowledge (i.e. source of truth). It is likely to be your
source code but it can be somewhere else (databases,
documents, ...).
▸
"
Do not duplicate. Extract and transform (code →
documentation, documents → code, ...) then augment this
knowledge. You need either automation or reconciliation
mechanisms.
@samuelroze - 2020
11 EXAMPLESOF USEFUL, LIVING, DOCUMENTATIONS
@samuelroze - 2020
1. COMMITS
@samuelroze - 2020
Every single developer knows what a commit is. It's
some code changes, associated with basically a title
and a description. That's it.
@samuelroze - 2020
While exploring this code... I know who, why and when the lines have changed.
@samuelroze - 2020
Each commit would give me the whole context about why this piece of code change.
@samuelroze - 2020
@samuelroze - 2020
1. COMMITS
With some hygiene commits can answer many WTF
questions, be used to auto-generate change logs and
drive automated versioning.
!
They can answer so much more things like which
piece of your code is the least stable, where do you
often have bugs, etc...
@samuelroze - 2020
2. CODE
COMMENTS
@samuelroze - 2020
I don't mean these ones.
@samuelroze - 2020
More these ones.
@samuelroze - 2020
2. CODE COMMENTS
@samuelroze - 2020
2. CODE COMMENTS
▸ Hard to measure the RoI of good comments.
@samuelroze - 2020
2. CODE COMMENTS
▸ Hard to measure the RoI of good comments.
▸
!
A study found that "40-60% of the maintenance
time is spent on studying the software prior
modifications because of the lack of appropriate
documentation".
@samuelroze - 2020
3. TESTS
@samuelroze - 2020
@samuelroze - 2020
@samuelroze - 2020
4. BDD
SCENARIOS
@samuelroze - 2020
BDD is a process that encourages collaboration among
developers, QA and non-technical or business
participants in a software project. It encourages teams
to use conversation and concrete examples to formalize a shared
understanding of how the application should behave.
Wikipedia
@samuelroze - 2020
4. BBD SCENARIOS
@samuelroze - 2020
4. BBD SCENARIOS
▸ Describe behaviour via examples in a human and
machine readable format.
@samuelroze - 2020
4. BBD SCENARIOS
▸ Describe behaviour via examples in a human and
machine readable format.
▸ This is a clear example of knowledge reconciliation: you have
some code that validates the BDD scenarios are
matching with the code.
@samuelroze - 2020
4. BBD SCENARIOS
▸ Describe behaviour via examples in a human and
machine readable format.
▸ This is a clear example of knowledge reconciliation: you have
some code that validates the BDD scenarios are
matching with the code.
▸ They can transform the way you work by being the
artefact used and understandable by all.
@samuelroze - 2020
AN EXAMPLE OF ONE SCENARIO
@samuelroze - 2020
EACH STEP DRIVES YOUR TESTS
This is a Behat context file.
@samuelroze - 2020
EACH SCENARIO BELONGS TO A FEATURE FILE.
@samuelroze - 2020
“Most teams initially embrace BDD for non-regression
testing purposes and end up realising that the bigger
benefits are somewhere else - in the early
conversations, using concrete examples and in the
resulting living documentation.”
Cyrille Martraire
@samuelroze - 2020
5. ADRS(ARCHITECTURE DECISION RECORD)
@samuelroze - 2020
WHAT ARE ADRS?
@samuelroze - 2020
WHAT ARE ADRS?
▸ A document that records a significant architecture
decision. It is split into three parts: Context, Decision and
Consequences. They are a record of why you decided
something at one point in time.
@samuelroze - 2020
WHAT ARE ADRS?
▸ A document that records a significant architecture
decision. It is split into three parts: Context, Decision and
Consequences. They are a record of why you decided
something at one point in time.
▸ Usually, you add them in your source code and
propose a decision via a pull-request. Discussions
and suggestions happen as PR comments.
@samuelroze - 2020
WHY ARE THEY THAT INTERESTING?
@samuelroze - 2020
WHY ARE THEY THAT INTERESTING?
▸ Up-front thinking. Writing the context & consequences
mostly force yourself (as the writer) to step back
and consider alternatives. The rubber duck theory.
@samuelroze - 2020
WHY ARE THEY THAT INTERESTING?
▸ Up-front thinking. Writing the context & consequences
mostly force yourself (as the writer) to step back
and consider alternatives. The rubber duck theory.
▸ Gives a chance for diverse thinking. It gives the time and the
space for everybody to contribute.
@samuelroze - 2020
WHY ARE THEY THAT INTERESTING?
▸ Up-front thinking. Writing the context & consequences
mostly force yourself (as the writer) to step back
and consider alternatives. The rubber duck theory.
▸ Gives a chance for diverse thinking. It gives the time and the
space for everybody to contribute.
▸ Fabulous record of why we ended-up where we are for new
joiners and your future self.
@samuelroze - 2020
@samuelroze - 2020
6. VISUAL DOCUMENTATION
WITH DIAGRAMS
@samuelroze - 2020
Diagrams are super useful but hard to maintain.
@samuelroze - 2020
...unless you generate them from code! Mermaid [5] in this example
@samuelroze - 2020
Mermaid in ADRs
@samuelroze - 2020
7. PUBLISHED DOCS
HOW TO MAKE IT MORE ACCESSIBLE THAN
GITHUB
@samuelroze - 2020
WHY PUBLISHING DOCUMENTATIONS?
@samuelroze - 2020
WHY PUBLISHING DOCUMENTATIONS?
▸ If everything is only accessible in GitHub or in the
code... you don't reach your documentation's full
potential.
@samuelroze - 2020
WHY PUBLISHING DOCUMENTATIONS?
▸ If everything is only accessible in GitHub or in the
code... you don't reach your documentation's full
potential.
▸ Tools like Mkdocs to publish a static documentation
from Markdown files. Gives you great looking docs.
@samuelroze - 2020
WHY PUBLISHING DOCUMENTATIONS?
▸ If everything is only accessible in GitHub or in the
code... you don't reach your documentation's full
potential.
▸ Tools like Mkdocs to publish a static documentation
from Markdown files. Gives you great looking docs.
▸
⁉
You now need to maintain these Markdown files?
@samuelroze - 2020
EXTRACT, TRANSFORM & AUGMENT!!
BUILD MKDOCS PLUGINS THAT WILL
READ YOUR CODE, YOUR CUCUMBER TESTS'
OUTPUTS, YOUR CODE ANNOTATIONS, ETC...
@samuelroze - 2020
@samuelroze - 2020
8. A LIVING ARCHITECTURE
DOCUMENTATION
@samuelroze - 2020
Not boring, multi faceted documentation (architecture & health)
@samuelroze - 2020
HOW WAS THIS EXAMPLE BUILT?
@samuelroze - 2020
HOW WAS THIS EXAMPLE BUILT?
▸ Whole architecture is a YAML file, which describes groups and
dependencies. It also points out to the AWS &
Kubernetes resource names.
@samuelroze - 2020
HOW WAS THIS EXAMPLE BUILT?
▸ Whole architecture is a YAML file, which describes groups and
dependencies. It also points out to the AWS &
Kubernetes resource names.
▸ The rest is a React application that draws the SVG,
pulls data from Kubernetes, CloudWatch and other
sources. Not OSS yet but hopefully we get there.
@samuelroze - 2020
9. LINTERS
@samuelroze - 2020
“Having tools that scream when you do
something wrong is yet another form of
documentation, and it is one of the most
efficient, since it brings the right
knowledge at the right time even to people
who weren’t aware of it.”
@samuelroze - 2020
LINTER FOR DATABASE MIGRATIONS
@samuelroze - 2020
LINTER FOR DATABASE MIGRATIONS
▸ The new rule:
!
Every migration needs to be non-
blocking SQL queries.
@samuelroze - 2020
LINTER FOR DATABASE MIGRATIONS
▸ The new rule:
!
Every migration needs to be non-
blocking SQL queries.
@samuelroze - 2020
LINTER FOR DATABASE MIGRATIONS
▸ The new rule:
!
Every migration needs to be non-
blocking SQL queries.
1. Option 1: you write it down somewhere, even in a pull-
request check-list.
@samuelroze - 2020
LINTER FOR DATABASE MIGRATIONS
▸ The new rule:
!
Every migration needs to be non-
blocking SQL queries.
1. Option 1: you write it down somewhere, even in a pull-
request check-list.
2.
!
Option 2: you write a linter that identifies these
queries and says "Noooo way." automatically.
@samuelroze - 2020
HIGH-AVAILABILITY CHECKER
@samuelroze - 2020
HIGH-AVAILABILITY CHECKER
▸
!
You need to make sure all your deployed
services are high-available.
@samuelroze - 2020
HIGH-AVAILABILITY CHECKER
▸
!
You need to make sure all your deployed
services are high-available.
▸ Option 1: Don't manually check these every week or
simply remind people about this.
@samuelroze - 2020
HIGH-AVAILABILITY CHECKER
▸
!
You need to make sure all your deployed
services are high-available.
▸ Option 1: Don't manually check these every week or
simply remind people about this.
▸
"
Option 2: Write a reconciliation script which pulls data from
your infrastructure, compares with your exceptions
and if breach, triggers an alert.
@samuelroze - 2020
THERE IS MORE.DDD
@samuelroze - 2020
DOCUMENTATION CAN ALSO HELP WITH...
Not building the wrong things. Documentation Driven Design. If
you share your product documentation before
building it, people will find issues much earlier.
!
Terraform: The authors iterated on a very long
Google Docs for many weeks before writing any piece
of code.
@samuelroze - 2020
Cost of change reminder [3]
@samuelroze - 2020
NOW...
WRAP UP.
@samuelroze - 2020
@samuelroze - 2020
1. Don't document what you don't need to document.
Otherwise you are loosing more time than gaining.
@samuelroze - 2020
1. Don't document what you don't need to document.
Otherwise you are loosing more time than gaining.
2. Identify and extract from authoritative sources of
knowledge. To keep it low effort.
@samuelroze - 2020
1. Don't document what you don't need to document.
Otherwise you are loosing more time than gaining.
2. Identify and extract from authoritative sources of
knowledge. To keep it low effort.
3. Augment existing knowledge by combining
multiple sources of information.
@samuelroze - 2020
1. Don't document what you don't need to document.
Otherwise you are loosing more time than gaining.
2. Identify and extract from authoritative sources of
knowledge. To keep it low effort.
3. Augment existing knowledge by combining
multiple sources of information.
4. Best documentation is providing the right
information and the right time.
@samuelroze - 2020
1. Don't document what you don't need to document.
Otherwise you are loosing more time than gaining.
2. Identify and extract from authoritative sources of
knowledge. To keep it low effort.
3. Augment existing knowledge by combining
multiple sources of information.
4. Best documentation is providing the right
information and the right time.
5. Documentation can also be a design tool
@samuelroze - 2020
THANK YOU!
AND CHECK THIS BOOK.
@samuelroze - 2020
REFERENCES
[1] Reducing Technical Debt: Using Persuasive Technology for Encouraging Software
Developers to Document Code
[2] Getting On Board: A Model for Integrating and Engaging New Employee
[3] Impact of Requirements Elicitation Processes on Success of Information System
Development Projects
[4] When Should I Write an Architecture Decision Record
[5] Mermaid
@samuelroze - 2020

Más contenido relacionado

Similar a Living documentation

the best code, is code never written
the best code, is code never writtenthe best code, is code never written
the best code, is code never writtenDaniel Davis
 
SpringOne Tour: The Influential Software Engineer
SpringOne Tour: The Influential Software EngineerSpringOne Tour: The Influential Software Engineer
SpringOne Tour: The Influential Software EngineerVMware Tanzu
 
apidays Paris 2022 - Let’s not make the diversity mistake in NoCode, Manon Me...
apidays Paris 2022 - Let’s not make the diversity mistake in NoCode, Manon Me...apidays Paris 2022 - Let’s not make the diversity mistake in NoCode, Manon Me...
apidays Paris 2022 - Let’s not make the diversity mistake in NoCode, Manon Me...apidays
 
Big guns for small guys (reloaded)
Big guns for small guys (reloaded)Big guns for small guys (reloaded)
Big guns for small guys (reloaded)Jorge López-Lago
 
2020 Enterprise IT Outlook
2020 Enterprise IT Outlook2020 Enterprise IT Outlook
2020 Enterprise IT OutlookRaymond Gao
 
The Research Software Encyclopedia
The Research Software EncyclopediaThe Research Software Encyclopedia
The Research Software EncyclopediaVanessa S
 
Dan North Embracinguncertaintyv3
Dan North Embracinguncertaintyv3Dan North Embracinguncertaintyv3
Dan North Embracinguncertaintyv3Adrian Treacy
 
Bilot 3mode
Bilot 3modeBilot 3mode
Bilot 3modeBilot
 
Continuous Documentation: The Best Time is Now
Continuous Documentation: The Best Time is NowContinuous Documentation: The Best Time is Now
Continuous Documentation: The Best Time is NowPronovix
 
Presentation Visuals
Presentation VisualsPresentation Visuals
Presentation Visualsbthat
 
The Soft Side of Software Development / Devoxx 2019
The Soft Side of Software Development / Devoxx 2019The Soft Side of Software Development / Devoxx 2019
The Soft Side of Software Development / Devoxx 2019🎤 Hanno Embregts 🎸
 
Develop like a designer
Develop like a designerDevelop like a designer
Develop like a designerJ+E Creative
 
Why your project's brand is more important than the code - SCRIPT
Why your project's brand is more important than the code - SCRIPTWhy your project's brand is more important than the code - SCRIPT
Why your project's brand is more important than the code - SCRIPTShane Curcuru
 
OSDC 2019 | Feature Branching considered Evil by Thierry de Pauw
OSDC 2019 | Feature Branching considered Evil by Thierry de PauwOSDC 2019 | Feature Branching considered Evil by Thierry de Pauw
OSDC 2019 | Feature Branching considered Evil by Thierry de PauwNETWAYS
 
Designing Mobile Solutions for Social & Economic Contexts
Designing Mobile Solutions for Social & Economic ContextsDesigning Mobile Solutions for Social & Economic Contexts
Designing Mobile Solutions for Social & Economic ContextsThoughtworks
 
Designing Mobile Solutions for Social & Economic Contexts
Designing Mobile Solutions for Social & Economic ContextsDesigning Mobile Solutions for Social & Economic Contexts
Designing Mobile Solutions for Social & Economic ContextsJonny Schneider
 
SFSCON23 - Tommaso Bailetti - Improving developer experience in Open Source P...
SFSCON23 - Tommaso Bailetti - Improving developer experience in Open Source P...SFSCON23 - Tommaso Bailetti - Improving developer experience in Open Source P...
SFSCON23 - Tommaso Bailetti - Improving developer experience in Open Source P...South Tyrol Free Software Conference
 
Designing Narrative Content Workshop
Designing Narrative Content WorkshopDesigning Narrative Content Workshop
Designing Narrative Content WorkshopMartha Rotter
 
Codemotion Milan 2018 - AI with a devops mindset: experimentation, sharing an...
Codemotion Milan 2018 - AI with a devops mindset: experimentation, sharing an...Codemotion Milan 2018 - AI with a devops mindset: experimentation, sharing an...
Codemotion Milan 2018 - AI with a devops mindset: experimentation, sharing an...Thiago de Faria
 

Similar a Living documentation (20)

the best code, is code never written
the best code, is code never writtenthe best code, is code never written
the best code, is code never written
 
SpringOne Tour: The Influential Software Engineer
SpringOne Tour: The Influential Software EngineerSpringOne Tour: The Influential Software Engineer
SpringOne Tour: The Influential Software Engineer
 
apidays Paris 2022 - Let’s not make the diversity mistake in NoCode, Manon Me...
apidays Paris 2022 - Let’s not make the diversity mistake in NoCode, Manon Me...apidays Paris 2022 - Let’s not make the diversity mistake in NoCode, Manon Me...
apidays Paris 2022 - Let’s not make the diversity mistake in NoCode, Manon Me...
 
Big guns for small guys (reloaded)
Big guns for small guys (reloaded)Big guns for small guys (reloaded)
Big guns for small guys (reloaded)
 
2020 Enterprise IT Outlook
2020 Enterprise IT Outlook2020 Enterprise IT Outlook
2020 Enterprise IT Outlook
 
The Research Software Encyclopedia
The Research Software EncyclopediaThe Research Software Encyclopedia
The Research Software Encyclopedia
 
Dan North Embracinguncertaintyv3
Dan North Embracinguncertaintyv3Dan North Embracinguncertaintyv3
Dan North Embracinguncertaintyv3
 
Bilot 3mode
Bilot 3modeBilot 3mode
Bilot 3mode
 
Continuous Documentation: The Best Time is Now
Continuous Documentation: The Best Time is NowContinuous Documentation: The Best Time is Now
Continuous Documentation: The Best Time is Now
 
Presentation Visuals
Presentation VisualsPresentation Visuals
Presentation Visuals
 
The Soft Side of Software Development / Devoxx 2019
The Soft Side of Software Development / Devoxx 2019The Soft Side of Software Development / Devoxx 2019
The Soft Side of Software Development / Devoxx 2019
 
Develop like a designer
Develop like a designerDevelop like a designer
Develop like a designer
 
Why your project's brand is more important than the code - SCRIPT
Why your project's brand is more important than the code - SCRIPTWhy your project's brand is more important than the code - SCRIPT
Why your project's brand is more important than the code - SCRIPT
 
OSDC 2019 | Feature Branching considered Evil by Thierry de Pauw
OSDC 2019 | Feature Branching considered Evil by Thierry de PauwOSDC 2019 | Feature Branching considered Evil by Thierry de Pauw
OSDC 2019 | Feature Branching considered Evil by Thierry de Pauw
 
Designing Mobile Solutions for Social & Economic Contexts
Designing Mobile Solutions for Social & Economic ContextsDesigning Mobile Solutions for Social & Economic Contexts
Designing Mobile Solutions for Social & Economic Contexts
 
Designing Mobile Solutions for Social & Economic Contexts
Designing Mobile Solutions for Social & Economic ContextsDesigning Mobile Solutions for Social & Economic Contexts
Designing Mobile Solutions for Social & Economic Contexts
 
Innovate or Die
Innovate or DieInnovate or Die
Innovate or Die
 
SFSCON23 - Tommaso Bailetti - Improving developer experience in Open Source P...
SFSCON23 - Tommaso Bailetti - Improving developer experience in Open Source P...SFSCON23 - Tommaso Bailetti - Improving developer experience in Open Source P...
SFSCON23 - Tommaso Bailetti - Improving developer experience in Open Source P...
 
Designing Narrative Content Workshop
Designing Narrative Content WorkshopDesigning Narrative Content Workshop
Designing Narrative Content Workshop
 
Codemotion Milan 2018 - AI with a devops mindset: experimentation, sharing an...
Codemotion Milan 2018 - AI with a devops mindset: experimentation, sharing an...Codemotion Milan 2018 - AI with a devops mindset: experimentation, sharing an...
Codemotion Milan 2018 - AI with a devops mindset: experimentation, sharing an...
 

Más de Samuel ROZE

How I started to love design patterns
How I started to love design patternsHow I started to love design patterns
How I started to love design patternsSamuel ROZE
 
Symfony Messenger (Symfony Live San Francisco)
Symfony Messenger (Symfony Live San Francisco)Symfony Messenger (Symfony Live San Francisco)
Symfony Messenger (Symfony Live San Francisco)Samuel ROZE
 
Micro services may not be the best idea
Micro services may not be the best ideaMicro services may not be the best idea
Micro services may not be the best ideaSamuel ROZE
 
Introduction to CQRS and Event Sourcing
Introduction to CQRS and Event SourcingIntroduction to CQRS and Event Sourcing
Introduction to CQRS and Event SourcingSamuel ROZE
 
CQRS and Event Sourcing in a Symfony application
CQRS and Event Sourcing in a Symfony applicationCQRS and Event Sourcing in a Symfony application
CQRS and Event Sourcing in a Symfony applicationSamuel ROZE
 
How I started to love design patterns
How I started to love design patternsHow I started to love design patterns
How I started to love design patternsSamuel ROZE
 
Take care of our micro services
Take care of our micro servicesTake care of our micro services
Take care of our micro servicesSamuel ROZE
 
(micro)services avec Symfony et Tolerance
(micro)services avec Symfony et Tolerance(micro)services avec Symfony et Tolerance
(micro)services avec Symfony et ToleranceSamuel ROZE
 
Using continuouspipe to speed up our workflows
Using continuouspipe to speed up our workflowsUsing continuouspipe to speed up our workflows
Using continuouspipe to speed up our workflowsSamuel ROZE
 
Symfony CoP: Form component
Symfony CoP: Form componentSymfony CoP: Form component
Symfony CoP: Form componentSamuel ROZE
 
Behat c'est plus que ça | Behat is more than that
Behat c'est plus que ça | Behat is more than thatBehat c'est plus que ça | Behat is more than that
Behat c'est plus que ça | Behat is more than thatSamuel ROZE
 
Docker orchestration with Kubernetes
Docker orchestration with KubernetesDocker orchestration with Kubernetes
Docker orchestration with KubernetesSamuel ROZE
 
Symfony et serialization avec JMS serializer
Symfony et serialization avec JMS serializer Symfony et serialization avec JMS serializer
Symfony et serialization avec JMS serializer Samuel ROZE
 

Más de Samuel ROZE (13)

How I started to love design patterns
How I started to love design patternsHow I started to love design patterns
How I started to love design patterns
 
Symfony Messenger (Symfony Live San Francisco)
Symfony Messenger (Symfony Live San Francisco)Symfony Messenger (Symfony Live San Francisco)
Symfony Messenger (Symfony Live San Francisco)
 
Micro services may not be the best idea
Micro services may not be the best ideaMicro services may not be the best idea
Micro services may not be the best idea
 
Introduction to CQRS and Event Sourcing
Introduction to CQRS and Event SourcingIntroduction to CQRS and Event Sourcing
Introduction to CQRS and Event Sourcing
 
CQRS and Event Sourcing in a Symfony application
CQRS and Event Sourcing in a Symfony applicationCQRS and Event Sourcing in a Symfony application
CQRS and Event Sourcing in a Symfony application
 
How I started to love design patterns
How I started to love design patternsHow I started to love design patterns
How I started to love design patterns
 
Take care of our micro services
Take care of our micro servicesTake care of our micro services
Take care of our micro services
 
(micro)services avec Symfony et Tolerance
(micro)services avec Symfony et Tolerance(micro)services avec Symfony et Tolerance
(micro)services avec Symfony et Tolerance
 
Using continuouspipe to speed up our workflows
Using continuouspipe to speed up our workflowsUsing continuouspipe to speed up our workflows
Using continuouspipe to speed up our workflows
 
Symfony CoP: Form component
Symfony CoP: Form componentSymfony CoP: Form component
Symfony CoP: Form component
 
Behat c'est plus que ça | Behat is more than that
Behat c'est plus que ça | Behat is more than thatBehat c'est plus que ça | Behat is more than that
Behat c'est plus que ça | Behat is more than that
 
Docker orchestration with Kubernetes
Docker orchestration with KubernetesDocker orchestration with Kubernetes
Docker orchestration with Kubernetes
 
Symfony et serialization avec JMS serializer
Symfony et serialization avec JMS serializer Symfony et serialization avec JMS serializer
Symfony et serialization avec JMS serializer
 

Último

Lecture 1: Basics of trigonometry (surveying)
Lecture 1: Basics of trigonometry (surveying)Lecture 1: Basics of trigonometry (surveying)
Lecture 1: Basics of trigonometry (surveying)Bahzad5
 
nvidia AI-gtc 2024 partial slide deck.pptx
nvidia AI-gtc 2024 partial slide deck.pptxnvidia AI-gtc 2024 partial slide deck.pptx
nvidia AI-gtc 2024 partial slide deck.pptxjasonsedano2
 
Best-NO1 Best Rohani Amil In Lahore Kala Ilam In Lahore Kala Jadu Amil In Lah...
Best-NO1 Best Rohani Amil In Lahore Kala Ilam In Lahore Kala Jadu Amil In Lah...Best-NO1 Best Rohani Amil In Lahore Kala Ilam In Lahore Kala Jadu Amil In Lah...
Best-NO1 Best Rohani Amil In Lahore Kala Ilam In Lahore Kala Jadu Amil In Lah...Amil baba
 
SATELITE COMMUNICATION UNIT 1 CEC352 REGULATION 2021 PPT BASICS OF SATELITE ....
SATELITE COMMUNICATION UNIT 1 CEC352 REGULATION 2021 PPT BASICS OF SATELITE ....SATELITE COMMUNICATION UNIT 1 CEC352 REGULATION 2021 PPT BASICS OF SATELITE ....
SATELITE COMMUNICATION UNIT 1 CEC352 REGULATION 2021 PPT BASICS OF SATELITE ....santhyamuthu1
 
Semiconductor Physics Background and Light Emitting Diode(LEDs)-.pptx
Semiconductor Physics Background and Light Emitting Diode(LEDs)-.pptxSemiconductor Physics Background and Light Emitting Diode(LEDs)-.pptx
Semiconductor Physics Background and Light Emitting Diode(LEDs)-.pptxbhoomijyani51
 
Multicomponent Spiral Wound Membrane Separation Model.pdf
Multicomponent Spiral Wound Membrane Separation Model.pdfMulticomponent Spiral Wound Membrane Separation Model.pdf
Multicomponent Spiral Wound Membrane Separation Model.pdfGiovanaGhasary1
 
Dev.bg DevOps March 2024 Monitoring & Logging
Dev.bg DevOps March 2024 Monitoring & LoggingDev.bg DevOps March 2024 Monitoring & Logging
Dev.bg DevOps March 2024 Monitoring & LoggingMarian Marinov
 
GENERAL CONDITIONS FOR CONTRACTS OF CIVIL ENGINEERING WORKS
GENERAL CONDITIONS  FOR  CONTRACTS OF CIVIL ENGINEERING WORKS GENERAL CONDITIONS  FOR  CONTRACTS OF CIVIL ENGINEERING WORKS
GENERAL CONDITIONS FOR CONTRACTS OF CIVIL ENGINEERING WORKS Bahzad5
 
EPE3163_Hydro power stations_Unit2_Lect2.pptx
EPE3163_Hydro power stations_Unit2_Lect2.pptxEPE3163_Hydro power stations_Unit2_Lect2.pptx
EPE3163_Hydro power stations_Unit2_Lect2.pptxJoseeMusabyimana
 
Mohs Scale of Hardness, Hardness Scale.pptx
Mohs Scale of Hardness, Hardness Scale.pptxMohs Scale of Hardness, Hardness Scale.pptx
Mohs Scale of Hardness, Hardness Scale.pptxKISHAN KUMAR
 
The relationship between iot and communication technology
The relationship between iot and communication technologyThe relationship between iot and communication technology
The relationship between iot and communication technologyabdulkadirmukarram03
 
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdf
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdfRenewable Energy & Entrepreneurship Workshop_21Feb2024.pdf
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdfodunowoeminence2019
 
sdfsadopkjpiosufoiasdoifjasldkjfl a asldkjflaskdjflkjsdsdf
sdfsadopkjpiosufoiasdoifjasldkjfl a asldkjflaskdjflkjsdsdfsdfsadopkjpiosufoiasdoifjasldkjfl a asldkjflaskdjflkjsdsdf
sdfsadopkjpiosufoiasdoifjasldkjfl a asldkjflaskdjflkjsdsdfJulia Kaye
 
Quasi-Stochastic Approximation: Algorithm Design Principles with Applications...
Quasi-Stochastic Approximation: Algorithm Design Principles with Applications...Quasi-Stochastic Approximation: Algorithm Design Principles with Applications...
Quasi-Stochastic Approximation: Algorithm Design Principles with Applications...Sean Meyn
 
ASME BPVC 2023 Section I para leer y entender
ASME BPVC 2023 Section I para leer y entenderASME BPVC 2023 Section I para leer y entender
ASME BPVC 2023 Section I para leer y entenderjuancarlos286641
 
Test of Significance of Large Samples for Mean = µ.pptx
Test of Significance of Large Samples for Mean = µ.pptxTest of Significance of Large Samples for Mean = µ.pptx
Test of Significance of Large Samples for Mean = µ.pptxHome
 
Vertical- Machining - Center - VMC -LMW-Machine-Tool-Division.pptx
Vertical- Machining - Center - VMC -LMW-Machine-Tool-Division.pptxVertical- Machining - Center - VMC -LMW-Machine-Tool-Division.pptx
Vertical- Machining - Center - VMC -LMW-Machine-Tool-Division.pptxLMW Machine Tool Division
 
Transforming Process Safety Management: Challenges, Benefits, and Transition ...
Transforming Process Safety Management: Challenges, Benefits, and Transition ...Transforming Process Safety Management: Challenges, Benefits, and Transition ...
Transforming Process Safety Management: Challenges, Benefits, and Transition ...soginsider
 

Último (20)

Présentation IIRB 2024 Marine Cordonnier.pdf
Présentation IIRB 2024 Marine Cordonnier.pdfPrésentation IIRB 2024 Marine Cordonnier.pdf
Présentation IIRB 2024 Marine Cordonnier.pdf
 
Lecture 1: Basics of trigonometry (surveying)
Lecture 1: Basics of trigonometry (surveying)Lecture 1: Basics of trigonometry (surveying)
Lecture 1: Basics of trigonometry (surveying)
 
nvidia AI-gtc 2024 partial slide deck.pptx
nvidia AI-gtc 2024 partial slide deck.pptxnvidia AI-gtc 2024 partial slide deck.pptx
nvidia AI-gtc 2024 partial slide deck.pptx
 
Best-NO1 Best Rohani Amil In Lahore Kala Ilam In Lahore Kala Jadu Amil In Lah...
Best-NO1 Best Rohani Amil In Lahore Kala Ilam In Lahore Kala Jadu Amil In Lah...Best-NO1 Best Rohani Amil In Lahore Kala Ilam In Lahore Kala Jadu Amil In Lah...
Best-NO1 Best Rohani Amil In Lahore Kala Ilam In Lahore Kala Jadu Amil In Lah...
 
Lecture 2 .pdf
Lecture 2                           .pdfLecture 2                           .pdf
Lecture 2 .pdf
 
SATELITE COMMUNICATION UNIT 1 CEC352 REGULATION 2021 PPT BASICS OF SATELITE ....
SATELITE COMMUNICATION UNIT 1 CEC352 REGULATION 2021 PPT BASICS OF SATELITE ....SATELITE COMMUNICATION UNIT 1 CEC352 REGULATION 2021 PPT BASICS OF SATELITE ....
SATELITE COMMUNICATION UNIT 1 CEC352 REGULATION 2021 PPT BASICS OF SATELITE ....
 
Semiconductor Physics Background and Light Emitting Diode(LEDs)-.pptx
Semiconductor Physics Background and Light Emitting Diode(LEDs)-.pptxSemiconductor Physics Background and Light Emitting Diode(LEDs)-.pptx
Semiconductor Physics Background and Light Emitting Diode(LEDs)-.pptx
 
Multicomponent Spiral Wound Membrane Separation Model.pdf
Multicomponent Spiral Wound Membrane Separation Model.pdfMulticomponent Spiral Wound Membrane Separation Model.pdf
Multicomponent Spiral Wound Membrane Separation Model.pdf
 
Dev.bg DevOps March 2024 Monitoring & Logging
Dev.bg DevOps March 2024 Monitoring & LoggingDev.bg DevOps March 2024 Monitoring & Logging
Dev.bg DevOps March 2024 Monitoring & Logging
 
GENERAL CONDITIONS FOR CONTRACTS OF CIVIL ENGINEERING WORKS
GENERAL CONDITIONS  FOR  CONTRACTS OF CIVIL ENGINEERING WORKS GENERAL CONDITIONS  FOR  CONTRACTS OF CIVIL ENGINEERING WORKS
GENERAL CONDITIONS FOR CONTRACTS OF CIVIL ENGINEERING WORKS
 
EPE3163_Hydro power stations_Unit2_Lect2.pptx
EPE3163_Hydro power stations_Unit2_Lect2.pptxEPE3163_Hydro power stations_Unit2_Lect2.pptx
EPE3163_Hydro power stations_Unit2_Lect2.pptx
 
Mohs Scale of Hardness, Hardness Scale.pptx
Mohs Scale of Hardness, Hardness Scale.pptxMohs Scale of Hardness, Hardness Scale.pptx
Mohs Scale of Hardness, Hardness Scale.pptx
 
The relationship between iot and communication technology
The relationship between iot and communication technologyThe relationship between iot and communication technology
The relationship between iot and communication technology
 
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdf
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdfRenewable Energy & Entrepreneurship Workshop_21Feb2024.pdf
Renewable Energy & Entrepreneurship Workshop_21Feb2024.pdf
 
sdfsadopkjpiosufoiasdoifjasldkjfl a asldkjflaskdjflkjsdsdf
sdfsadopkjpiosufoiasdoifjasldkjfl a asldkjflaskdjflkjsdsdfsdfsadopkjpiosufoiasdoifjasldkjfl a asldkjflaskdjflkjsdsdf
sdfsadopkjpiosufoiasdoifjasldkjfl a asldkjflaskdjflkjsdsdf
 
Quasi-Stochastic Approximation: Algorithm Design Principles with Applications...
Quasi-Stochastic Approximation: Algorithm Design Principles with Applications...Quasi-Stochastic Approximation: Algorithm Design Principles with Applications...
Quasi-Stochastic Approximation: Algorithm Design Principles with Applications...
 
ASME BPVC 2023 Section I para leer y entender
ASME BPVC 2023 Section I para leer y entenderASME BPVC 2023 Section I para leer y entender
ASME BPVC 2023 Section I para leer y entender
 
Test of Significance of Large Samples for Mean = µ.pptx
Test of Significance of Large Samples for Mean = µ.pptxTest of Significance of Large Samples for Mean = µ.pptx
Test of Significance of Large Samples for Mean = µ.pptx
 
Vertical- Machining - Center - VMC -LMW-Machine-Tool-Division.pptx
Vertical- Machining - Center - VMC -LMW-Machine-Tool-Division.pptxVertical- Machining - Center - VMC -LMW-Machine-Tool-Division.pptx
Vertical- Machining - Center - VMC -LMW-Machine-Tool-Division.pptx
 
Transforming Process Safety Management: Challenges, Benefits, and Transition ...
Transforming Process Safety Management: Challenges, Benefits, and Transition ...Transforming Process Safety Management: Challenges, Benefits, and Transition ...
Transforming Process Safety Management: Challenges, Benefits, and Transition ...
 

Living documentation

  • 2. While the audience of this talk is technical people, it is almost non technical. It's aim is to give you (hopefully new) insights about what documentation is and can be, gathered from experience and this great book. @samuelroze - 2020
  • 3. WHICH DOCUMENTATION ARE WE TALKING ABOUT? @samuelroze - 2020
  • 4. WHICH DOCUMENTATION ARE WE TALKING ABOUT? ▸Internal. The audience is the project's members and direct stakeholders. The aim is to explain intricacies of the concepts, decisions, architecture and (little bit) how the product behaves. @samuelroze - 2020
  • 5. WHICH DOCUMENTATION ARE WE TALKING ABOUT? ▸Internal. The audience is the project's members and direct stakeholders. The aim is to explain intricacies of the concepts, decisions, architecture and (little bit) how the product behaves. ▸External. The audience is the project's customers. It's mostly about how to use it and a how it behaves. @samuelroze - 2020
  • 6. WHAT IS (INTERNAL) DOCUMENTATION USEFUL FOR? @samuelroze - 2020
  • 8. DOCUMENTATION CAN HELP WITH... (1/3) @samuelroze - 2020
  • 9. DOCUMENTATION CAN HELP WITH... (1/3) ▸Reducing technical debt. Usually, tech debt is because an engineer or a team didn't have all the context they needed to have. @samuelroze - 2020
  • 10. DOCUMENTATION CAN HELP WITH... (1/3) ▸Reducing technical debt. Usually, tech debt is because an engineer or a team didn't have all the context they needed to have. ▸ ! "Outdated or lacking documentation is a considerable contributor to increased costs of software systems maintenance" - Yulia Sh. et al. [1] @samuelroze - 2020
  • 11. DOCUMENTATION CAN HELP WITH... (2/3) @samuelroze - 2020
  • 12. DOCUMENTATION CAN HELP WITH... (2/3) ▸On-boarding new engineers. As a company scales, on-boarding engineers can be a huge amount of effort without good documentation. @samuelroze - 2020
  • 13. DOCUMENTATION CAN HELP WITH... (2/3) ▸On-boarding new engineers. As a company scales, on-boarding engineers can be a huge amount of effort without good documentation. ▸ ! Overall, we are pretty bad at communicating context and getting people onboarded [2] @samuelroze - 2020
  • 14. DOCUMENTATION CAN HELP WITH... (3/3) Conversations. By reducing the amount of mis- understanding thanks to a clear common vocabulary (ubiquitous language) and reducing un-necessary interruptions because knowledge is easily accessible. ! Flags “What do you mean by X?”. "Is the field X synchronised?" "What time 'Morning' starts and ends?" ... @samuelroze - 2020
  • 15. Cost of translation reminder. @samuelroze - 2020
  • 16. SOUNDS FABULOUS... WHAT'S WRONG WITH OUR CURRENT DOCUMENTATIONS? @samuelroze - 2020
  • 18. ▸ What to document is unclear. We sometimes are overloaded with information which either is known by everybody or is not relevant. @samuelroze - 2020
  • 19. ▸ What to document is unclear. We sometimes are overloaded with information which either is known by everybody or is not relevant. ▸ Out of date. You know when reading a documentation that you need to check the date at which is was written... @samuelroze - 2020
  • 20. ▸ What to document is unclear. We sometimes are overloaded with information which either is known by everybody or is not relevant. ▸ Out of date. You know when reading a documentation that you need to check the date at which is was written... ▸ Boring. It's usually not a great experience to go and... RTFM. (i.e. flat & ugly files/slides) @samuelroze - 2020
  • 21. 4 PRINCIPLES OF A LIVING DOCUMENTATION @samuelroze - 2020
  • 22. 4 PRINCIPLES OF A LIVING DOCUMENTATION 1. Reliable. You don't worry about the version. @samuelroze - 2020
  • 23. 4 PRINCIPLES OF A LIVING DOCUMENTATION 1. Reliable. You don't worry about the version. 2. Low effort. Simple to read & simple to maintain. @samuelroze - 2020
  • 24. 4 PRINCIPLES OF A LIVING DOCUMENTATION 1. Reliable. You don't worry about the version. 2. Low effort. Simple to read & simple to maintain. 3. Collaborative. Communication first, "sediment" knowledge later. @samuelroze - 2020
  • 25. 4 PRINCIPLES OF A LIVING DOCUMENTATION 1. Reliable. You don't worry about the version. 2. Low effort. Simple to read & simple to maintain. 3. Collaborative. Communication first, "sediment" knowledge later. 4. Insightful. Explicit decisions, things that are not that good, or yet unknowns. @samuelroze - 2020
  • 26. WHAT SHOULD YOU DOCUMENT? @samuelroze - 2020
  • 27. WHAT SHOULD YOU DOCUMENT? 1. Generic knowledge. How is Symfony working, how to run an SQL query, what is Kafka about, how to use GitHub, ... @samuelroze - 2020
  • 28. WHAT SHOULD YOU DOCUMENT? 1. Generic knowledge. How is Symfony working, how to run an SQL query, what is Kafka about, how to use GitHub, ... 2. Specific knowledge. Your architecture, decisions you took so far, details about your industry, ... @samuelroze - 2020
  • 29. WHAT SHOULD YOU DOCUMENT? 1. Generic knowledge. How is Symfony working, how to run an SQL query, what is Kafka about, how to use GitHub, ... 2. Specific knowledge. Your architecture, decisions you took so far, details about your industry, ... ▸ ✋ In shot, focus only here. @samuelroze - 2020
  • 30. HOW DO YOU ENSURE 'FRESHNESS'? @samuelroze - 2020
  • 31. HOW DO YOU ENSURE 'FRESHNESS'? ▸ ! The knowledge already exists. You have authoritative sources of knowledge (i.e. source of truth). It is likely to be your source code but it can be somewhere else (databases, documents, ...). @samuelroze - 2020
  • 32. HOW DO YOU ENSURE 'FRESHNESS'? ▸ ! The knowledge already exists. You have authoritative sources of knowledge (i.e. source of truth). It is likely to be your source code but it can be somewhere else (databases, documents, ...). ▸ " Do not duplicate. Extract and transform (code → documentation, documents → code, ...) then augment this knowledge. You need either automation or reconciliation mechanisms. @samuelroze - 2020
  • 33. 11 EXAMPLESOF USEFUL, LIVING, DOCUMENTATIONS @samuelroze - 2020
  • 35. Every single developer knows what a commit is. It's some code changes, associated with basically a title and a description. That's it. @samuelroze - 2020
  • 36. While exploring this code... I know who, why and when the lines have changed. @samuelroze - 2020
  • 37. Each commit would give me the whole context about why this piece of code change. @samuelroze - 2020
  • 39. 1. COMMITS With some hygiene commits can answer many WTF questions, be used to auto-generate change logs and drive automated versioning. ! They can answer so much more things like which piece of your code is the least stable, where do you often have bugs, etc... @samuelroze - 2020
  • 41. I don't mean these ones. @samuelroze - 2020
  • 44. 2. CODE COMMENTS ▸ Hard to measure the RoI of good comments. @samuelroze - 2020
  • 45. 2. CODE COMMENTS ▸ Hard to measure the RoI of good comments. ▸ ! A study found that "40-60% of the maintenance time is spent on studying the software prior modifications because of the lack of appropriate documentation". @samuelroze - 2020
  • 50. BDD is a process that encourages collaboration among developers, QA and non-technical or business participants in a software project. It encourages teams to use conversation and concrete examples to formalize a shared understanding of how the application should behave. Wikipedia @samuelroze - 2020
  • 52. 4. BBD SCENARIOS ▸ Describe behaviour via examples in a human and machine readable format. @samuelroze - 2020
  • 53. 4. BBD SCENARIOS ▸ Describe behaviour via examples in a human and machine readable format. ▸ This is a clear example of knowledge reconciliation: you have some code that validates the BDD scenarios are matching with the code. @samuelroze - 2020
  • 54. 4. BBD SCENARIOS ▸ Describe behaviour via examples in a human and machine readable format. ▸ This is a clear example of knowledge reconciliation: you have some code that validates the BDD scenarios are matching with the code. ▸ They can transform the way you work by being the artefact used and understandable by all. @samuelroze - 2020
  • 55. AN EXAMPLE OF ONE SCENARIO @samuelroze - 2020
  • 56. EACH STEP DRIVES YOUR TESTS This is a Behat context file. @samuelroze - 2020
  • 57. EACH SCENARIO BELONGS TO A FEATURE FILE. @samuelroze - 2020
  • 58. “Most teams initially embrace BDD for non-regression testing purposes and end up realising that the bigger benefits are somewhere else - in the early conversations, using concrete examples and in the resulting living documentation.” Cyrille Martraire @samuelroze - 2020
  • 59. 5. ADRS(ARCHITECTURE DECISION RECORD) @samuelroze - 2020
  • 61. WHAT ARE ADRS? ▸ A document that records a significant architecture decision. It is split into three parts: Context, Decision and Consequences. They are a record of why you decided something at one point in time. @samuelroze - 2020
  • 62. WHAT ARE ADRS? ▸ A document that records a significant architecture decision. It is split into three parts: Context, Decision and Consequences. They are a record of why you decided something at one point in time. ▸ Usually, you add them in your source code and propose a decision via a pull-request. Discussions and suggestions happen as PR comments. @samuelroze - 2020
  • 63. WHY ARE THEY THAT INTERESTING? @samuelroze - 2020
  • 64. WHY ARE THEY THAT INTERESTING? ▸ Up-front thinking. Writing the context & consequences mostly force yourself (as the writer) to step back and consider alternatives. The rubber duck theory. @samuelroze - 2020
  • 65. WHY ARE THEY THAT INTERESTING? ▸ Up-front thinking. Writing the context & consequences mostly force yourself (as the writer) to step back and consider alternatives. The rubber duck theory. ▸ Gives a chance for diverse thinking. It gives the time and the space for everybody to contribute. @samuelroze - 2020
  • 66. WHY ARE THEY THAT INTERESTING? ▸ Up-front thinking. Writing the context & consequences mostly force yourself (as the writer) to step back and consider alternatives. The rubber duck theory. ▸ Gives a chance for diverse thinking. It gives the time and the space for everybody to contribute. ▸ Fabulous record of why we ended-up where we are for new joiners and your future self. @samuelroze - 2020
  • 68. 6. VISUAL DOCUMENTATION WITH DIAGRAMS @samuelroze - 2020
  • 69. Diagrams are super useful but hard to maintain. @samuelroze - 2020
  • 70. ...unless you generate them from code! Mermaid [5] in this example @samuelroze - 2020
  • 72. 7. PUBLISHED DOCS HOW TO MAKE IT MORE ACCESSIBLE THAN GITHUB @samuelroze - 2020
  • 74. WHY PUBLISHING DOCUMENTATIONS? ▸ If everything is only accessible in GitHub or in the code... you don't reach your documentation's full potential. @samuelroze - 2020
  • 75. WHY PUBLISHING DOCUMENTATIONS? ▸ If everything is only accessible in GitHub or in the code... you don't reach your documentation's full potential. ▸ Tools like Mkdocs to publish a static documentation from Markdown files. Gives you great looking docs. @samuelroze - 2020
  • 76. WHY PUBLISHING DOCUMENTATIONS? ▸ If everything is only accessible in GitHub or in the code... you don't reach your documentation's full potential. ▸ Tools like Mkdocs to publish a static documentation from Markdown files. Gives you great looking docs. ▸ ⁉ You now need to maintain these Markdown files? @samuelroze - 2020
  • 77. EXTRACT, TRANSFORM & AUGMENT!! BUILD MKDOCS PLUGINS THAT WILL READ YOUR CODE, YOUR CUCUMBER TESTS' OUTPUTS, YOUR CODE ANNOTATIONS, ETC... @samuelroze - 2020
  • 79. 8. A LIVING ARCHITECTURE DOCUMENTATION @samuelroze - 2020
  • 80. Not boring, multi faceted documentation (architecture & health) @samuelroze - 2020
  • 81. HOW WAS THIS EXAMPLE BUILT? @samuelroze - 2020
  • 82. HOW WAS THIS EXAMPLE BUILT? ▸ Whole architecture is a YAML file, which describes groups and dependencies. It also points out to the AWS & Kubernetes resource names. @samuelroze - 2020
  • 83. HOW WAS THIS EXAMPLE BUILT? ▸ Whole architecture is a YAML file, which describes groups and dependencies. It also points out to the AWS & Kubernetes resource names. ▸ The rest is a React application that draws the SVG, pulls data from Kubernetes, CloudWatch and other sources. Not OSS yet but hopefully we get there. @samuelroze - 2020
  • 85. “Having tools that scream when you do something wrong is yet another form of documentation, and it is one of the most efficient, since it brings the right knowledge at the right time even to people who weren’t aware of it.” @samuelroze - 2020
  • 86. LINTER FOR DATABASE MIGRATIONS @samuelroze - 2020
  • 87. LINTER FOR DATABASE MIGRATIONS ▸ The new rule: ! Every migration needs to be non- blocking SQL queries. @samuelroze - 2020
  • 88. LINTER FOR DATABASE MIGRATIONS ▸ The new rule: ! Every migration needs to be non- blocking SQL queries. @samuelroze - 2020
  • 89. LINTER FOR DATABASE MIGRATIONS ▸ The new rule: ! Every migration needs to be non- blocking SQL queries. 1. Option 1: you write it down somewhere, even in a pull- request check-list. @samuelroze - 2020
  • 90. LINTER FOR DATABASE MIGRATIONS ▸ The new rule: ! Every migration needs to be non- blocking SQL queries. 1. Option 1: you write it down somewhere, even in a pull- request check-list. 2. ! Option 2: you write a linter that identifies these queries and says "Noooo way." automatically. @samuelroze - 2020
  • 92. HIGH-AVAILABILITY CHECKER ▸ ! You need to make sure all your deployed services are high-available. @samuelroze - 2020
  • 93. HIGH-AVAILABILITY CHECKER ▸ ! You need to make sure all your deployed services are high-available. ▸ Option 1: Don't manually check these every week or simply remind people about this. @samuelroze - 2020
  • 94. HIGH-AVAILABILITY CHECKER ▸ ! You need to make sure all your deployed services are high-available. ▸ Option 1: Don't manually check these every week or simply remind people about this. ▸ " Option 2: Write a reconciliation script which pulls data from your infrastructure, compares with your exceptions and if breach, triggers an alert. @samuelroze - 2020
  • 96. DOCUMENTATION CAN ALSO HELP WITH... Not building the wrong things. Documentation Driven Design. If you share your product documentation before building it, people will find issues much earlier. ! Terraform: The authors iterated on a very long Google Docs for many weeks before writing any piece of code. @samuelroze - 2020
  • 97. Cost of change reminder [3] @samuelroze - 2020
  • 100. 1. Don't document what you don't need to document. Otherwise you are loosing more time than gaining. @samuelroze - 2020
  • 101. 1. Don't document what you don't need to document. Otherwise you are loosing more time than gaining. 2. Identify and extract from authoritative sources of knowledge. To keep it low effort. @samuelroze - 2020
  • 102. 1. Don't document what you don't need to document. Otherwise you are loosing more time than gaining. 2. Identify and extract from authoritative sources of knowledge. To keep it low effort. 3. Augment existing knowledge by combining multiple sources of information. @samuelroze - 2020
  • 103. 1. Don't document what you don't need to document. Otherwise you are loosing more time than gaining. 2. Identify and extract from authoritative sources of knowledge. To keep it low effort. 3. Augment existing knowledge by combining multiple sources of information. 4. Best documentation is providing the right information and the right time. @samuelroze - 2020
  • 104. 1. Don't document what you don't need to document. Otherwise you are loosing more time than gaining. 2. Identify and extract from authoritative sources of knowledge. To keep it low effort. 3. Augment existing knowledge by combining multiple sources of information. 4. Best documentation is providing the right information and the right time. 5. Documentation can also be a design tool @samuelroze - 2020
  • 105. THANK YOU! AND CHECK THIS BOOK. @samuelroze - 2020
  • 106. REFERENCES [1] Reducing Technical Debt: Using Persuasive Technology for Encouraging Software Developers to Document Code [2] Getting On Board: A Model for Integrating and Engaging New Employee [3] Impact of Requirements Elicitation Processes on Success of Information System Development Projects [4] When Should I Write an Architecture Decision Record [5] Mermaid @samuelroze - 2020