Onboarding to new code with runtime code maps

So I've recently been inspired by:

A well-known blog post by Aleksey Kladov (matklad) about Architecture.md,

Conversations with AppMap users

As you probably know, the job market is good for developers these days! Lots of companies are in hiring mode - Shopify, for example, is doubling their team with 2021 hires in 2021.

Starting a new job is exciting, but also stressful. If you're hiring, it's important help your new hires feel at ease in their new position. There are lots of things you can do to prepare, but I will just focus on one aspect here: getting familiar with the code base.

Hopefully you have a Wiki for new hire orientation, that's built and maintained by new hires themselves. Once a new hire has all their new accounts, knows where to find things, and has had lunch with the team, it's time to take a ticket and fix or improve something. And that's where Architecture.md comes it. To quote Aleksey:

Roughly, it takes 2x more time to write a patch if you are unfamiliar with the project, but it takes 10x more time to figure out where you should change the code.

Yeah. The biggest challenge is just knowing where the relevant code is!

Now, in Aleksey's post, he recommends against detailed links to code - because the code is going to change, and the links will become stale. So, I've thought about that and I'm proposing a way to include detailed code links and keep them fresh.

Here's my suggestion in a nutshell: enhance Architecture.md with links to interactive code maps, and provide developers with a command that they can run to generate these code maps. In the video above, I'm using the Rails Sample App for my demo. A rake task generates all the code maps used by Architecture.md:

Once a developer has run this command, all the AppMaps used by Architecture.md are guaranteed up-to-date with the code. So, they can be used as a supplement to the text content in Architecture.md - you can navigate from the Markdown, into code maps, directly into source code, and back. The code maps include HTTP server requests, dependency libraries, and detailed SQL, so there's a wealth of information and detail that new hires can use to get oriented.

Check out the video for a walkthrough. Here are links to some resources presented in the video:

Rails Sample App - appmap-e2e branch

AppMap Discord

AppMap quick start guides

Do you have other tips and tricks for making a great Architecture.md? Let us know in the comments!