Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.

Living documentation

452 vues

Publié le

Why a living documentation is a great asset to improve your teams' velocity, how to create one and real life examples.

Publié dans : Ingénierie
  • Soyez le premier à commenter

Living documentation

  1. 1. LIVING DOCUMENTATION @samuelroze - 2020
  2. 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. 3. WHICH DOCUMENTATION ARE WE TALKING ABOUT? @samuelroze - 2020
  4. 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. 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. 6. WHAT IS (INTERNAL) DOCUMENTATION USEFUL FOR? @samuelroze - 2020
  7. 7. REDUCING WASTED TIME! @samuelroze - 2020
  8. 8. DOCUMENTATION CAN HELP WITH... (1/3) @samuelroze - 2020
  9. 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. 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. 11. DOCUMENTATION CAN HELP WITH... (2/3) @samuelroze - 2020
  12. 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. 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. 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. 15. Cost of translation reminder. @samuelroze - 2020
  16. 16. SOUNDS FABULOUS... WHAT'S WRONG WITH OUR CURRENT DOCUMENTATIONS? @samuelroze - 2020
  17. 17. @samuelroze - 2020
  18. 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. 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. 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. 21. 4 PRINCIPLES OF A LIVING DOCUMENTATION @samuelroze - 2020
  22. 22. 4 PRINCIPLES OF A LIVING DOCUMENTATION 1. Reliable. You don't worry about the version. @samuelroze - 2020
  23. 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. 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. 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. 26. WHAT SHOULD YOU DOCUMENT? @samuelroze - 2020
  27. 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. 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. 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. 30. HOW DO YOU ENSURE 'FRESHNESS'? @samuelroze - 2020
  31. 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. 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. 33. 11 EXAMPLESOF USEFUL, LIVING, DOCUMENTATIONS @samuelroze - 2020
  34. 34. 1. COMMITS @samuelroze - 2020
  35. 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. 36. While exploring this code... I know who, why and when the lines have changed. @samuelroze - 2020
  37. 37. Each commit would give me the whole context about why this piece of code change. @samuelroze - 2020
  38. 38. @samuelroze - 2020
  39. 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. 40. 2. CODE COMMENTS @samuelroze - 2020
  41. 41. I don't mean these ones. @samuelroze - 2020
  42. 42. More these ones. @samuelroze - 2020
  43. 43. 2. CODE COMMENTS @samuelroze - 2020
  44. 44. 2. CODE COMMENTS ▸ Hard to measure the RoI of good comments. @samuelroze - 2020
  45. 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. 46. 3. TESTS @samuelroze - 2020
  47. 47. @samuelroze - 2020
  48. 48. @samuelroze - 2020
  49. 49. 4. BDD SCENARIOS @samuelroze - 2020
  50. 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. 51. 4. BBD SCENARIOS @samuelroze - 2020
  52. 52. 4. BBD SCENARIOS ▸ Describe behaviour via examples in a human and machine readable format. @samuelroze - 2020
  53. 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. 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. 55. AN EXAMPLE OF ONE SCENARIO @samuelroze - 2020
  56. 56. EACH STEP DRIVES YOUR TESTS This is a Behat context file. @samuelroze - 2020
  57. 57. EACH SCENARIO BELONGS TO A FEATURE FILE. @samuelroze - 2020
  58. 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. 59. 5. ADRS(ARCHITECTURE DECISION RECORD) @samuelroze - 2020
  60. 60. WHAT ARE ADRS? @samuelroze - 2020
  61. 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. 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. 63. WHY ARE THEY THAT INTERESTING? @samuelroze - 2020
  64. 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. 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. 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. 67. @samuelroze - 2020
  68. 68. 6. VISUAL DOCUMENTATION WITH DIAGRAMS @samuelroze - 2020
  69. 69. Diagrams are super useful but hard to maintain. @samuelroze - 2020
  70. 70. ...unless you generate them from code! Mermaid [5] in this example @samuelroze - 2020
  71. 71. Mermaid in ADRs @samuelroze - 2020
  72. 72. 7. PUBLISHED DOCS HOW TO MAKE IT MORE ACCESSIBLE THAN GITHUB @samuelroze - 2020
  73. 73. WHY PUBLISHING DOCUMENTATIONS? @samuelroze - 2020
  74. 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. 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. 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. 77. EXTRACT, TRANSFORM & AUGMENT!! BUILD MKDOCS PLUGINS THAT WILL READ YOUR CODE, YOUR CUCUMBER TESTS' OUTPUTS, YOUR CODE ANNOTATIONS, ETC... @samuelroze - 2020
  78. 78. @samuelroze - 2020
  79. 79. 8. A LIVING ARCHITECTURE DOCUMENTATION @samuelroze - 2020
  80. 80. Not boring, multi faceted documentation (architecture & health) @samuelroze - 2020
  81. 81. HOW WAS THIS EXAMPLE BUILT? @samuelroze - 2020
  82. 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. 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. 84. 9. LINTERS @samuelroze - 2020
  85. 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. 86. LINTER FOR DATABASE MIGRATIONS @samuelroze - 2020
  87. 87. LINTER FOR DATABASE MIGRATIONS ▸ The new rule: ! Every migration needs to be non- blocking SQL queries. @samuelroze - 2020
  88. 88. LINTER FOR DATABASE MIGRATIONS ▸ The new rule: ! Every migration needs to be non- blocking SQL queries. @samuelroze - 2020
  89. 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. 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. 91. HIGH-AVAILABILITY CHECKER @samuelroze - 2020
  92. 92. HIGH-AVAILABILITY CHECKER ▸ ! You need to make sure all your deployed services are high-available. @samuelroze - 2020
  93. 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. 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. 95. THERE IS MORE.DDD @samuelroze - 2020
  96. 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. 97. Cost of change reminder [3] @samuelroze - 2020
  98. 98. NOW... WRAP UP. @samuelroze - 2020
  99. 99. @samuelroze - 2020
  100. 100. 1. Don't document what you don't need to document. Otherwise you are loosing more time than gaining. @samuelroze - 2020
  101. 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. 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. 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. 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. 105. THANK YOU! AND CHECK THIS BOOK. @samuelroze - 2020
  106. 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

×