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.

AWS GenAI LIVE image

How is generative AI increasing efficiency?

Join AWS GenAI LIVE! to find out how gen AI is reshaping productivity, streamlining processes, and driving innovation.

Learn more

Top comments (0)

Billboard image

Create up to 10 Postgres Databases on Neon's free plan.

If you're starting a new project, Neon has got your databases covered. No credit cards. No trials. No getting in your way.

Try Neon for Free →

👋 Kindness is contagious

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

Okay