The Smartest Way to Onboard Developers

Transcript

Joining a new team should be a pretty exciting experience for all software engineers. Unfortunately, most onboarding experiences are not the greatest. Usually there's documentation that's missing, outdated, or in some cases just simply incorrect. Then you have to go into the codebase and figure out what the heck is going on. Why did they write this in a certain way? How should I be using a certain class or structure?

If you're new here, my name is Stu. I've got 15 years of .NET experience coupled with AWS development and architecture. I'm here today to tell you about CodeTour and what it can do for your onboarding experience. So let's dive into VS Code right now and let's go and take a look.

So now we're here inside of the VS Code instance, and one of the first things that we're going to need to do is install the CodeTour extension. So to do that, I'm going to come across to the extensions and type in CodeTour. Then you're going to look for the one by Jonathan Carter and we're going to click install.

Once that's installed, a couple of things will happen. First, if there's an existing tour already set up inside of your solution, it'll be highlighted in the pane down here in the bottom left hand corner. Otherwise, you can click Record Tour and start recording a tour around your codebase.

So let's just type in "example" to start creating our tour. As you can see, it's now appeared down in the pane in the bottom left and we can add tour steps. So if we wanted an introduction to the tour, we can just click the Add Tour Step, give it a name, and then say "this is an introduction" and then we can click Save Step. Then we can go around our codebase, like clicking on this new plus symbol that's appeared on line 12, and say "this is a constructor". We can go through and add detailed comments, thought processes, and examples in different areas of our codebase.

So now let's jump over to say our health check class and say "this is some code". Then we can provide a code block, and a comment. Once you add a code block to a tour, you can see we have the Insert Code option which will insert the code that we put in there right at the right place. But we don't want to do that for now.

The other thing that happens when we start going through and building these tours, as you can see, is the icon that's now appeared next to each line number. So if I go back to the local container, you can see I now have an icon here which means there is a tour with an explanation on it.

Now as you're going through and creating this tour, one of the things that you might accidentally do is get things in the wrong order. But that's okay, because what we can do is come down to the pane in the bottom left hand corner and then just click the up or down arrows which you can see here and reorder things.

Then when we think we're done with the code tour, we can right click on it and say Preview Tour. Then it will give us the experience of a guided tour through our codebase. What you'll see down here is the Next button, and as we click that it will jump to the next section of our code. So this can be a really powerful way of talking through specific features, how different bits and pieces are linked together. Especially when you're using patterns like Mediator, it's not always clear what should be handled next, why things are handled in a certain way, and this can make it really clear for developers.

The best part is when you have this associated with a Git repository, which I don't for this example, but when you do then these code tours are versioned. Because what happens is there is a .tours folder that is created, and inside of here we have all of the tours that we have. In my case I've only got a single tour, so I've got a single JSON file. Inside of this JSON file, it basically lists the title, so I can go and quickly change that and save the file and see it update in the pane in the lower left hand corner. Then it gives us all of the different bits and pieces. We have the file, which is basically the file name, the line number it's on, and if we want to go and reorder stuff in here as well, we can do that, that's absolutely fine and then it'll take effect inside the tour. As you can see, now "this is a constructor" is back as step number two.

Now one of the problems with this is the line numbers will move, and there's a couple of different ways that we can prevent this problem from happening. The first way is in the extension settings itself. So if I go to the settings, there's a couple of different bits that we can do here. We can override the tours directory, so by default if you remember it's .tours. We're going to leave that as default for now. There is this "prompt for workspace tours" so when you load up this inside Visual Studio Code, a notification will appear down on the bottom right corner that says "there's a CodeTour here, would you like to run it?" That's what this option here controls.

The record mode basically says whether it's a line number or whether it's a pattern. It's worth noting that this pattern or line number should be set once and shouldn't mix and match the two. The other thing that we can set is whether we want to show the markers in the guttering or not, and that for reference is just this icon here.

So as I mentioned, there's another way that you can help prevent the line numbers becoming out of sync, and that is to use a GitHub workflow action. So there is this CodeTour Watch extension that's been written that you can run in your GitHub Actions, and I believe there is one as well for Azure Pipelines. Basically what this does is anytime there's a pull request open, it checks for changes within your tours and the files that are changed as well, and then adds a comment to your PR that basically says "hey, this is not quite right". Obviously, if you have this as a separate workflow, you can make that workflow fail as well and hold the PR open until the comments are updated. So this can be really handy in terms of forcing that documentation to always be up to date, something which you can't necessarily do with a comment per se.

Now the other thing that I want to show you with these CodeTour is you don't necessarily have to do it inside of the solution. You can do one-off tours and then give them to other people to load into their IDEs as well. One of the ways that we can do this is either copy the example.

.tour file, or we can right click on the tour, if I just end the tour quickly, and I can click Export Tour. That means it's really quick and easy for me to share a tour that I've built to maybe explain something to someone and give them a guided walkthrough without me necessarily having to be online. I can go through, write all my comments down, show them how different bits and pieces work, click Export Tour, give them the file.

You can also turn these tours into Gists as well, and there is an extension called GistPad, again written by Jonathan Carter, that you can take your CodeTour and export it to a Gist.

As I mentioned earlier, this is available for IntelliJ IDE as well. This is not .NET specific or anything like that. This is a third party extension that's been written for IntelliJ which provides the same kind of experiences as well.

The documentation for VS CodeTour is really good. It explains all of the other bits and pieces that you can do. So I've gone through the basics of recording, going through the different steps that you can do, how to rearrange steps and stuff like this. But you can do conditional tours, so if there's functionality that's specific to Windows, you can make that happen as well. It goes through all the different bits and pieces that you can do.

The one that I haven't personally used yet, which is why I haven't showed it, is these shell commands. So if you want to run npm run compile, you can see this graphic now is showing you that you can literally click it once, it'll open up a terminal, it'll run the commands. This makes it a really powerful onboarding experience.

I really hope that you can see how CodeTour can be a really powerful onboarding experience.

If you enjoyed this video, consider subscribing to the YouTube channel for more content like this.