apidays LIVE Australia 2021 - Re-thinking Software Architecture Documentation by Graham Lea, Archium
0 likes1,698 views
The document discusses the evolution and importance of software architecture documentation, emphasizing the need for improved knowledge flow in agile and decentralized environments. It highlights various strategies, such as short design documents, architecture decision records, and living documentation, to facilitate communication and adaptability among teams. The emphasis is on the value of maintaining comprehensive and up-to-date documentation to support rapid changes in software engineering.
apidays LIVE Australia 2021 - Re-thinking Software Architecture Documentation by Graham Lea, Archium
- 2. Bill & Ted Face The Music - Orion Pictures
- 4. 500,000 BC Speech & Language Broke the constraint of: Limited expression Tim Evanson
- 5. New York JULY Australia SEPTEMBER Singapore APRIL Helsinki & North MARCH Paris DECEMBER London OCTOBER Jakarta FEBRUARY Hong Kong AUGUST JUNE India MAY Check out our API Conferences here 50+ events since 2012, 14 countries, 2,000+ speakers, 50,000+ attendees, 300k+ online community Want to talk at one of our conferences? Apply to speak here
- 7. 4000 BC Writing Broke constraint: Density Bjørn Christian Tørrissen
- 8. 2500 BC Papyrus / Parchment Broke constraint: Location
- 9. 1440 Printing Press Broke constraint: Expensive Duplication
- 10. 1831 Electric Telegraph Broke constraint: Latency (Speed of light!) Cardiff Council Flat Holm Project
- 11. 1894 Radio Comms Broke constraint: Physical connection (Light Speed)
- 12. Fax Machine Phonograph Film Broadcast Radio Televison
- 14. 1989 World Wide Web Broke constraint: Access to Publication CERN
- 15. 2000s Smartphones Broke constraint: Physical connection (Internet)
- 17. Documentation Documentation Documentation Documentation Documentation Documentation Documentation Documentation Documentation
- 18. As we break the constraints of knowledge flow, technology accelerates, and society advances.
- 22. Increasing Software Architecture Knowledge Flow (Why and How)
- 23. Increasing Software Architecture Knowledge Flow (Why and How) Peek
- 24. The Documentation Stereotype Architect in corner office writing specs?
- 25. The Documentation Stereotype Architect in corner office writing specs? Software architecture documentation: knowledge-sharing, unconstrained by time, location, and departmental partitions
- 26. Why should we be thinking about knowledge flow?
- 28. The pace at which we change our systems has accelerated (several orders of magnitude) Software Engineering Has Changed
- 29. Software Engineering Has Changed Deliver much smaller batches of changes much more frequently
- 30. Software Engineering Has Changed Our systems are more automated Automated Testing Continuous Deployment Infrastructure Automation
- 31. Software Engineering Has Changed Our systems are more distributed (and complex)
- 32. Software Engineering Has Changed O’Reily - Microservices Adoption in 2020 Postman - State of APIs Report 2020
- 33. Software Engineering Has Changed O’Reily - Microservices Adoption in 2020 Postman - State of APIs Report 2020 125%
- 34. Software Engineering Has Changed Our teams are more autonomous Central Mandates Trust
- 35. Software Engineering Has Changed It’s a good thing!
- 36. Software Engineering Has Changed
- 37. Software Engineering Has Changed For the better!
- 38. Software Architecture Knowledge Flow Is More Important Than Ever
- 39. Architecture Knowledge Flow The creation of architecture knowledge is decentralised Contributing to knowledge flow has to become part of everybody’s role
- 40. Architecture Knowledge Flow DevOps & Microservices decouple teams’ delivery But teams are still depending on the work on others at runtime, and have others depending on them Service Service Service Service Service Service
- 41. Architecture Knowledge Flow Service Service Service Service Service Service Team Team Team Team Team Team DevOps & Microservices decouple teams’ delivery But teams are still depending on the work on others at runtime, and have others depending on them
- 42. Architecture Knowledge Flow Teams need inbound knowledge flow to give them confidence that they’re integrating correctly Service Service Service Service Service Service Team Team Team Team Team Team
- 43. Architecture Knowledge Flow Teams should provide outbound knowledge flow to to their dependents to minimise confusion, failures, and expensive coordination Service Service Service Service Service Service Team Team Team Team Team Team
- 44. Architecture Knowledge Flow P.S. Good knowledge flow almost always goes both ways Service Service Service Service Service Service Team Team Team Team Team Team
- 45. Architecture Knowledge Flow Agile means there’s far fewer big plans. Each team is building their own plan as they go, and maybe updating it daily.
- 46. Architecture Knowledge Flow Agile means there’s far fewer big plans. Each team is building their own plan as they go, and maybe updating it daily.
- 47. Architecture Knowledge Flow These changes create new knowledge that needs to flow to people whose upcoming decisions and work might depend on them
- 48. Architecture Knowledge Flow These changes create new knowledge that needs to flow to people whose upcoming decisions and work might depend on them
- 49. Architecture Knowledge Flow As architectures become more complex, no one can keep it all in their head Twitter
- 50. Architecture Knowledge Flow Teams need access to knowledge about the high-level design and behaviour of the system to understand what it does and how they can improve it Twitter
- 51. Architecture Knowledge Flow The complexity means a single big picture is probably useless This “big picture” knowledge needs to be filterable, linked, and explorable Twitter
- 52. Architecture Knowledge Flow Investment in documentation and knowledge discovery is predictive of productivity
- 53. Knowledge Flow: We’re Not Very Good At It
- 54. We're Not Very Good At It With the rise of agile methods, documentation has taken a back seat in many organisations
- 55. We're Not Very Good At It “We're agile, we don’t do documentation”
- 56. Big Design Up Front Mountains of Documentation We're Not Very Good At It “We're agile, we don’t do documentation”
- 57. Big Design Up Front Mountains of Documentation No Design Up Front No Documentation We're Not Very Good At It
- 58. Borrowing from Lean, agile methods are anti-waste We're Not Very Good At It
- 59. Borrowing from Lean, agile methods are anti-waste Agile is anti-wasteful design and wasteful documentation We're Not Very Good At It
- 60. We're Not Very Good At It Agile Manifesto: “Face-to-face communication!”
- 61. We're Not Very Good At It Agile Manifesto: “Face-to-face communication!” If we rely on conversation we regress 500,000 years
- 62. Documentation: #2 way to learn about APIs We're Not Very Good At It
- 63. Poor Documentation is the #1 API Obstacle We're Not Very Good At It
- 64. Software Engineering has changed Knowledge flow is more important We’re not very good at it (yet) Why
- 65. How Do We Increase Knowledge Flow?
- 66. Changes to systems have become frequent, iterative, and automated Knowledge flow needs to follow suit: frequent, iterative, and automated Increasing Knowledge Flow
- 67. Here’s the approaches agile orgs are using to increase architecture knowledge flow Increasing Knowledge Flow
- 69. Short Design Documents Also called "one-pagers" or "RFCs" (“Request for Comment”)
- 70. Short Design Documents Describe the design of a single service or feature Similar content to an architecture spec, but less formal
- 71. Short Design Documents Primary purpose is to seek feedback (Not communicate instructions)
- 72. Short Design Documents Often published in a collaboration tool so discussion can be recorded with design Mousiga - CC-BY-SA
- 74. Architecture Decision Records Design docs record service micro-architecture ADRs record and distribute macro-architecture decisions
- 75. Architecture Decision Records Standardisation of “pipes" Cross-cutting concerns
- 76. Architecture Decision Records Documents how the decision was made (Not just the outcome)
- 77. Architecture Decision Records New team members can learn why things are the way they are With rationale recorded, we can see when the decision is no longer relevant
- 79. Service Catalogues Describe every service, in brief, in one place List the most important info people need Link to other sources with more detail State Library of NSW
- 80. Service Catalogues Not as technical as design docs Ideal overview for new starters, testers, Ops, management, Product
- 81. Service Catalogues Challenges: Making it comprehensive Keeping it up to date
- 83. Monitoring & Observability Knowledge flow doesn’t just happen between people! We learn from our systems as they’re running And when they're not! 🙀
- 84. Monitoring & Observability Monitoring: Diagnostic telemetry emitted by our systems Logs Traces Metrics Alerts
- 85. Monitoring & Observability Observability: Getting answers to questions that you aren’t specifically monitoring for Telemetry designed for exploration
- 87. Architecture Diagrams Architecture diagrams try to give an overview of the system structure Michel Triana (CC-BY-SA 3.0)
- 88. As many formats as diagrams What makes a good one? Open Networking Foundation (CC-BY-SA 3.0) Architecture Diagrams
- 89. Think of diagrams like a product: Choose a format that best suits the user’s needs Architecture Diagrams
- 91. Some different ways to get diagrams and/or models… Architecture Diagrams
- 92. Draw manually e.g. draw.io, Gliffy, whiteboard Big Advantage: Full control over appearance Disadvantages: Time-consuming Quickly obsolete Architecture Diagrams
- 93. Create a model manually e.g. Archi, MagicDraw Big Advantage: Generate multiple views Disadvantages: Still time-consuming Quickly obsolete Architecture Diagrams
- 94. Generate from text DSL e.g. Mermaid JS, PlantUML Big Advantages: Faster Focus on information Disadvantage: Still gets obsolete Architecture Diagrams
- 95. Generate a model from code e.g. Structurizr Big Advantage: As up to date as annotations Disadvantage: Internal architecture Architecture Diagrams
- 96. Generate model from telemetry e.g. Archium Advantages: Represents reality of prod Examine many views Filter, explore Disadvantage: Needs broad telemetry Architecture Diagrams
- 97. How do people discover diagrams? Architecture Diagrams
- 98. How do people discover diagrams? Think about creating a diagram catalogue Or link from a service catalogue Architecture Diagrams
- 99. Tech Radars Maintain oversight of what tech your org is leveraging, experimenting with, and retiring Thoughtworks
- 100. Runbooks Document standard procedures for maintenance and failure scenarios
- 101. Living Documentation Set of practices for automating the creation and maintenance of documentation so that it changes at the same pace as the system
- 102. Archium
- 103. Archium Combination of: Service Catalogue Diagram Library Living Documentation
- 104. Archium Automates Modelling Decreases Manual Effort Increases Detail Detail Automation Manual Service Catalogues & Architecture Diagrams
- 106. Populates the service catalogue with the architecture model of the actual running system
- 107. We can explore diagrams of different views e.g. a single feature
- 108. Or: everything inbound and outbound for a service
- 109. Which features of the system does a service support?
- 110. Which services and APIs are used when handling requests for a feature?
- 111. Archium We’ve got a ginormous roadmap of exciting things that we want to do with this rich architecture model
- 112. Archium Currently enrolling beta customers Get in touch if you’d like a demo! https://archium.io
- 114. Knowledge Flow: Wrap-Up Software Engineering has changed We’re optimising for rapid change & decentralised, autonomous design Knowledge flow is more important than ever
- 115. Knowledge Flow: Wrap-Up Big Design Up Front Architect Finalised specs Stale documents
- 116. Knowledge Flow: Wrap-Up Big Design Up Front Architect Finalised specs Stale documents No Design Up Front No one No documentation Ad hoc oral history
- 117. Knowledge Flow: Wrap-Up Big Design Up Front Architect Finalised specs Stale documents No Design Up Front No one No docs Ad hoc oral history Just Enough Design Up Front Teams Living Documentation Continuous Knowledge Flow
- 118. https://archium.io/ hello@archium.io Graham Lea @evolvable Thanks! 🎉 Continuous Knowledge Flow 🎉
- 119. New York JULY Australia SEPTEMBER Singapore APRIL Helsinki & North MARCH Paris DECEMBER London OCTOBER Jakarta FEBRUARY Hong Kong AUGUST JUNE India MAY Check out our API Conferences here 50+ events since 2012, 14 countries, 2,000+ speakers, 50,000+ attendees, 300k+ online community Want to talk at one of our conferences? Apply to speak here