The document discusses the importance and principles of effective living documentation, emphasizing its role in facilitating understanding among project members and stakeholders. It highlights the need for clear, concise, and up-to-date documentation that reduces technical debt and aids in onboarding new engineers. The document also outlines various types of documentation, such as architecture decision records and behavior-driven development scenarios, providing examples of effective practices.

1. LIVING
DOCUMENTATION
@samuelroze - 2020

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

7. REDUCING WASTED TIME!
@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

17. @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

34. 1. COMMITS
@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

38. @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

40. 2. CODE
COMMENTS
@samuelroze - 2020

41. I don't mean these ones.
@samuelroze - 2020

42. More these ones.
@samuelroze - 2020

43. 2. CODE COMMENTS
@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

46. 3. TESTS
@samuelroze - 2020

47. @samuelroze - 2020

48. @samuelroze - 2020

49. 4. BDD
SCENARIOS
@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

51. 4. BBD SCENARIOS
@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

60. WHAT ARE ADRS?
@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

67. @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

71. Mermaid in ADRs
@samuelroze - 2020

72. 7. PUBLISHED DOCS
HOW TO MAKE IT MORE ACCESSIBLE THAN
GITHUB
@samuelroze - 2020

73. WHY PUBLISHING DOCUMENTATIONS?
@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

78. @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

84. 9. LINTERS
@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

91. HIGH-AVAILABILITY CHECKER
@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

95. THERE IS MORE.DDD
@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

98. NOW...
WRAP UP.
@samuelroze - 2020

99. @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