January 26th, 2021

Onboard to new projects faster with CodeTour

author avatar
Ben Potter
Developer Advocate


Understanding how a new codebase works is difficult. Traditionally, developers have used either inline comments or external documentation to explain how things work.

These methods can work fairly well for developers that already have some familiarity with the code; however, they are not ideal for onboarding (or reboarding) new engineers to the team.

The current tools we have for onboarding developers aren't great.

  • Inline comments cannot link to external resources (chat threads, articles, docs)
  • External docs are disconnected from the codebase and often focus on concepts, not reasoning or flow

Enter CodeTour

CodeTour is a VS Code extension that allows development teams to visually explain a codebase.

Our new tour for code-server covers the key areas of the codebase: the CLI, express server routes, web proxies, and how our VS Code patch works.

With CodeTour, developers can add the much-needed context in their codebase through a collection of tour “steps” with the following attributes:

  • Built into your IDE/codebase (like comments)
  • Supports markdown (headings, links, code samples)
  • Ability to link to other steps (or tours)

The impact on developer flow

  • New contributors don’t have to rely on docs for an initial introduction
    • “Onboarding” sections of docs are often outdated
    • Docs do not highlight the “flow” of a codebase, especially the new/complicated sections
  • The tour is directly in their dev environment
    • Easy to reference blocks of code
    • Can include interactive prompts (run commands, insert code blocks)
    • Can still link to external sources

Coder + CodeTour = 💗

With Coder, development teams can source-control their development environments and run them in their cloud. We can configure a Coder image to automatically install the CodeTour extension and save an extra step in the onboarding process. Coder images can also contain any other extensions, software, or dependencies that a project needs.

This demo uses Coder to automatically provision a developer workspace with the necessary dependencies (including the CodeTour extension) installed.

To add the CodeTour extension to Coder images, you’ll need to include a configure script that runs on startup. To do this, add the following line to your Dockerfile:

COPY [ "configure", "/coder/configure" ]

Then, create the configure file in the same directory and edit it

$ touch configure
$ chmod +x configure
$ vi configure

In the configure file, we want to tell code-server to install a new extension. In this case, CodeTour.

# Configure script that runs on environment startup

# Install CodeTour extension on code-server
/tmp/coder/code-server/bin/code-server --install-extension vsls-contrib.codetour

Related resources:

What are your thoughts on this post? Let me know on Twitter.

If you liked this, share on Twitter, Hacker News, LinkedIn or Reddit


Enjoy what you read?

Subscribe to our newsletter

By signing up, you agree to our Privacy Policy and Terms of service.