Living documentation
1 like810 views
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.
![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](https://image.slidesharecdn.com/living-documentation-201025130351/85/Living-documentation-10-320.jpg)
![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](https://image.slidesharecdn.com/living-documentation-201025130351/85/Living-documentation-13-320.jpg)
![...unless you generate them from code! Mermaid [5] in this example
@samuelroze - 2020](https://image.slidesharecdn.com/living-documentation-201025130351/85/Living-documentation-70-320.jpg)
![Cost of change reminder [3]
@samuelroze - 2020](https://image.slidesharecdn.com/living-documentation-201025130351/85/Living-documentation-97-320.jpg)
![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](https://image.slidesharecdn.com/living-documentation-201025130351/85/Living-documentation-106-320.jpg)
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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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