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