Last month, I gave a talk at RailsConf 2021 titled "Teach your code to describe its own architecture". If you weren’t able to watch it during the conference, don’t worry -- I’m going to share a recap of my talk in a series of four, short blog posts and videos.
This first post recaps the intro of my presentation. You can watch this part of my talk in the video clip shown above, and take a look at how I framed the architecture documentation problem and solution for RailsConf attendees. I’d love to hear if it resonates with you in the AppMap Discord!
Problem
- Architecture documents and diagrams are always out of date.
- As developers, the docs we make for end users aren’t the same as the ones we need for our own work.
- The freedom to make decisions about code design now belongs to developers, not architects. So we as developers need a better way of communicating and explaining our decisions to other developers.
Solution
- A new kind of documentation that developers create as they work so it’s available when newcomers to the code need it
- This new kind of documentation should always be:
- Up-to-date Wrong documentation is worse than useless -- it’s misleading.
- Interactive A static picture isn’t powerful enough.
- Contextual Traditional architecture documentation is too big and complex to be immediately useful.
- As close to the code as possible Ideally, the documentation is in the code, because that’s where we’re working.
Coming up next
In Parts 2, 3 and 4, I’m going to recap the demo portions of my RailsConf talk. Using tools that automatically generate documentation and visualizations of architecture and code design, I’ll auto-document end-to-end code and data flows, web services and the relational database schema.
Top comments (0)