DEV Community

0 seconds of 6 minutes, 35 secondsVolume 90%
Press shift question mark to access a list of keyboard shortcuts
00:00
00:00
06:35
 
Kevin Gilpin for AppMap

Posted on • Edited on

9 3

We need a better way to communicate and explain our code decisions

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.

Heroku

Simplify your DevOps and maximize your time.

Since 2007, Heroku has been the go-to platform for developers as it monitors uptime, performance, and infrastructure concerns, allowing you to focus on writing code.

Learn More

Top comments (0)

Eliminate Context Switching and Maximize Productivity

Pieces.app

Pieces Copilot is your personalized workflow assistant, working alongside your favorite apps. Ask questions about entire repositories, generate contextualized code, save and reuse useful snippets, and streamline your development process.

Learn more

👋 Kindness is contagious

Please leave a ❤️ or a friendly comment on this post if you found it helpful!

Okay