How can we effectively explain large codebases?

Hello DEV!

After starting to wrap up on NextSketch 2, we decided to write on the issue NextSketch 2 is planning to solve; How do we efficiently explain huge projects?

The Problem

Often times when trying to understand the way a huge codebase works, we turn to documentation, which is sometimes not the best way to get started. People experienced with the Project aren't always available to query (especially if they're in a different time zone), and not everyone is the best at explaining. Language can also be a huge barrier to getting up to speed.

Often, the context of the explanation can get lost in our language semantics. We think that Diagrams are a much more universally understood way of explaining how the project works from a 10,000ft high perspective. Using diagrams in this case (compared to text-based docs), are much easier to parse, and preserve more context.

How can NextSketch 2 help?

This is why we started working on NextSketch 2.

For those who don't know, NextSketch 2 is an IntelliJ-Platform Plugin for designing diagrams explaining how your project architecture to others. It provides a fast editor experience, the ability to create multiple levels of diagrams, attach source files, and store diagrams right inside the project, making it self-documenting. Being a Plugin, it also makes the overhead of using an additional tool as slim as possible.

To be clear, NextSketch 2 is not a tool to generate diagrams automatically from code. Diagrams such as these often have questionable utility as there is not much insight to be gained from looking at the code-graph instead of just reading the code itself.

We're hoping to release in January of 2023 if everything goes well! Also, let us know below how you get started on large codebases in the comments!

Thanks for Reading!