RailsConf 2021 - Teach your code to describe its own architecture

I'm excited to announce that I will be speaking at RailsConf 2021 - Teach your code to describe its own architecture! My presentation will be available to watch on-demand once the conference begins on April 12, 2021. On April 14 at 4:10 PM ET, I will host a session in Discord which will include a “group watch” of the talk, plus a Q&A. Here’s a sneak peek at what you can expect from my presentation:

There aren’t many universal truths in software development, but here’s one: Architecture documents and diagrams are always out of date.

As I personally experienced - trying to integrate my previous startup's cloud-first Rails app with a Windows data center product - a lack of accurate, up-to-date information about software architecture is really harmful to developer productivity and happiness.

The lack of accurate, up-to-date information about software architecture is primarily the result of developers writing documentation for end users rather than for themselves. But since developers are the ones making architecture and code design decisions, we are also responsible for communicating and explaining our decisions to other developers.

In my presentation, I will will outline why a new kind of documentation is needed -- one that’s created by teaching code to document itself, so newcomers to the code have access to information when they need it. With three different tools, I will demonstrate how such documentation can be automatically generated, along with visualizations of architecture and code design.

In AppLand’s ongoing State of Software Architecture Quality survey, 84% of respondents said they’d like to have up-to-date diagrams and visualizations of code structure. And yet only 19% reported both using and being happy with existing code/architecture visualization tools. Clearly, there’s a need for better architecture documentation. As codebases continue to grow larger and more complex, now more than ever developers need documentation and visualizations that are always up-to-date, interactive, contextual and as close to the code as possible.

So, check out my RailsConf talk next week to learn more about how to automatically generate documents and diagrams of code architecture, and how to use this information to improve code understanding and code quality. Register here to attend, we’ll see you there!