Last month, I gave a talk at RailsConf 2021 on how to 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.
This first post recaps the intro of my presentation. You can watch this part of my talk in the video clip included below, or 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 Slack!
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 portion of my RailsConf talk. Using tools that automatically generate documentation and visualizations of architecture and code design, I’ll be documenting end-to-end flows, web services and data model details.
Get AppMap