code-tour: Onboard Engineers without Docs

I've just released code-tour: a lightweight JavaScript tool designed to simplify the onboarding process for new engineers. I built it while onboarding to my new job at Curology.

The Problem with External Docs

External documentation is a hidden dependency in applications. Docs are notoriously difficult to maintain with an evolving codebase. There's typically no direct link between the code and its documentation. Every time a new engineer onboards, they play Documentation Routlette and discover all sorts of problems and inconsistencies.

The code-tour Solution

code-tour takes a different approach by embedding the knowledge typically found in external docs directly within the code itself. This creates a more self-documenting codebase that guides new engineers through the project's structure and patterns.

How It Works

The tool is simple to use:

1. Install Node.js
2. Run yarn install in the project's root directory
3. Execute ./code-tour.js

You can customize the tour by editing the tour-stops.js file. Each stop on the tour is defined by a simple object:

{
    "title": "Welcome to the Project",
    "description": "This is the entry point of our application.",
    "filePath": "src/index.js",
    "startLine": 1,
    "endLine": 10
}

code-tour will display the specified lines of code for each stop, providing context and explanations as you guide new team members through the codebase.

Benefits

• Keeps onboarding information close to the code it describes
• Provides an interactive, guided tour of your codebase
• Easy to update as your project evolves, as there will be some coupling in your IDE between the code tour stops and your codebase.

Check out the GitHub repository.