DEV Community

0 seconds of 9 minutes, 15 secondsVolume 90%
Press shift question mark to access a list of keyboard shortcuts
00:00
00:00
09:15
 
Kevin Gilpin for AppMap

Posted on • Edited on

10

Onboarding to new code with runtime code maps

So I've recently been inspired by:

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:

bundle exec rake appmap:architecture
Enter fullscreen mode Exit fullscreen mode

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:

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

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

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

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

Okay