DEV Community

0 seconds of 0 secondsVolume 90%
Press shift question mark to access a list of keyboard shortcuts
00:00
00:00
00:00
 
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.

Image of AssemblyAI

Automatic Speech Recognition with AssemblyAI

Experience near-human accuracy, low-latency performance, and advanced Speech AI capabilities with AssemblyAI's Speech-to-Text API. Sign up today and get $50 in API credit. No credit card required.

Try the API

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

Immerse yourself in a wealth of knowledge with this piece, supported by the inclusive DEV Community—every developer, no matter where they are in their journey, is invited to contribute to our collective wisdom.

A simple “thank you” goes a long way—express your gratitude below in the comments!

Gathering insights enriches our journey on DEV and fortifies our community ties. Did you find this article valuable? Taking a moment to thank the author can have a significant impact.

Okay