Onboarding to Code: When More Text Doesn't Help
- Jun 30
- 6 min read
Every developer knows the feeling of being completely lost when first dropping into a new codebase.
"Go read the code" is the dreaded refrain, because chances are that the docs are out of date or are some LLM's slop dissertation, and because everyone knows that understanding has to be built personally. And usually the best you can get is an experienced coworker to patiently answer questions.
But AI has changed this, right?
While it's the closest thing we have to an infinitely patient coworker, current tooling falls short for a few reasons. And those are worth looking at because they tell us a lot about how we can make things better.
This is a problem we've thought about a lot. Our background is in secure code development, reverse engineering, and vulnerability research, which is the professional version of "understand code nobody wrote docs for, under pressure, without asking the author." So we've felt this pain, and now we're sharing our thoughts on it.
Why Text Falls Short for Understanding Code
It's not that text is useless, it's great for plenty of things. Code is written as text. But when code is run, two properties emerge and differentiate it from normal text: time and space.
Time, because it matters what order the code runs in. A function's name tells you what it does, but it tells you nothing about what order functions ran in, or how many times, or that it's an only-when-something-happened-earlier function.
Space, because it matters what path the code takes. The same line of code can mean totally different things depending on how you got there. The order and combination of calling functions can subtly affect the state in the function you're in now. "Where does this get called from?" is not a question you ask once, from one place, and if you keep asking that question you see the real structure of code. It's a graph, and the shape of it matters.
Asking an AI assistant to explain a flow like that results in a paragraph or an awkward ASCII block diagram. Something like: "handleRequest validates the token, then calls resolveUser, which checks the cache before falling back to the database…". Somewhere around the third "which" you notice you've started drawing boxes on a notepad, because you're trying to rebuild a branching, ordered structure from text that only goes one direction.
And that's the issue. The information you need has a shape, and the paragraph flattens it out, so you end up rebuilding the shape in your head every time you're stuck reading text. And reading too much text is basically the problem of onboarding in a nutshell. It's not the fault of the writer, it's that text isn't the right tool for the job.
Onboarding is Understanding in Two Directions
Onboarding is really just building understanding, and people have been studying how that works for a long time. The useful takeaway from decades of program comprehension research is that you build it from two directions at once, and we can improve the experience by understanding these elements.
(retrieved from https://webhome.cs.uvic.ca/~mstorey/papers/jss.pdf).
Top-down is where you usually start: a rough mental map of the big pieces and how they connect. Bottom-up is the reverse: you stare at a specific chunk of code and work out what it's actually doing.
The real magic though, is in the next layer down: tying those high-level concepts like "the auth system" to specific code flows and locations. This is where the "support goal-directed, hypothesis-driven comprehension" and "provide orientation cues" from the figure above really come into play.
AI is genuinely good at the bottom-up half. Ask what a function does or how the password check works, and you get a solid (if verbose) answer about that specific piece. This is a huge quality of life, and we shouldn't ignore it.
Top-down is shakier though, and when it comes to orientation and putting things together, that's where it isn't much help. An assistant can hand you a high-level description, and it can explain a snippet, but the thing you actually need while onboarding is to understand how a snippet fits in the bigger picture, and how you get to it.
This is what the design elements from the figure above point at, and it's exactly the stuff that text does poorly, for the same time-and-space reasons we mentioned before.
Visuals Improve Speed: People Measured This, a While Ago
We're not the first to notice any of this. Researchers built tools to attack exactly the problem of orienting in unfamiliar code, following control flow, answering "what calls what." They measured whether they helped, and the results were clear.
REACHER, an interactive call-graph tool, made developers over 5x more successful at answering reachability questions, and dropped average task time from 11.1 to 7.2 minutes. The Java Whyline, which helped answer "why did this happen?" by tracing backward through the code, made people about 3x more successful and roughly 2x faster in related tasks. Stacksplorer, which visualizes the callers and callees around a method, had developers finishing 3 of 4 maintenance tasks significantly faster.
The pattern is: give people an interactive, visual way to move through code, and they get faster and more accurate at understanding it. And it wasn't because they were the most beautiful diagrams. As far as visual aesthetics go… Well, they were built a long time ago.
Let's be honest, this research is old. All the examples we cited are from 2009–2011, back when the hottest IDE was Eclipse and AI was something you played video games against.
But the underlying finding isn't about the era of the tools, it's about how people understand code, and that hasn't changed. Text makes you rebuild the shape in your head; interactive visuals hand you the shape directly.
And yes, your IDE has a call hierarchy, and yes, you can generate Mermaid diagrams with LLMs. Those help, and they look a lot like the screenshots of some of the tools we've talked about. The gap is that they're static and shallow. A call hierarchy answers one question and stops, a flat diagram is either too big to be useful or only shows one tiny corner of the code, and neither lets you keep pulling the thread across files and see the big picture.
The best tools for understanding are the ones you can explore with or interrogate. That's the key, because you don't know in advance all the questions to which you'll need the answers.
VizDev: Interactive Visuals for Understanding Code
That last point is the whole reason VizDev exists, to change "go read the code" to "show me the code," in a way that makes the onboarding process better. We've built something you can actually explore and pivot with to build understanding.
VizDev plugs into the IDEs you already use, and turns the code in front of you into interactive visualizations, fast. Not a diagram you generate and screenshot, but something you move through: follow a call out across files, trace how control actually reaches the function you're staring at, see the shape of a flow instead of reconstructing it in your head.
Plus, every piece of it links straight back to the code, so you're up to date on the structure of code as you move through it. These advantages are what helps build the connective tissue we mentioned earlier, the top-down meets bottom-up stitching, where you build understanding by moving through the code.
One parting tip for onboarding, whether or not you ever try VizDev: pick a piece of interesting behavior and step through it in a debugger. Doing this gives specific location anchoring and spatial memory to help understand cross-file interactions. By stepping through code or looking at stack traces, you'll build those intuitive connections, plus see real example values for variables of interest. Plus, it forces you to get your debugging environment set up!
We built VizDev because we wanted it to exist and it didn't. We've spent years understanding code and explaining the details of how it works, and now we're trying to make that easier for everyone. If you've wished for the same thing, join the waitlist on our landing page. We're letting people in quickly right now, and getting users' honest feedback has been amazing so far.
