Tourist for Visual Studio Code
What's all this about?
Tourist is a new approach to documentation that allows programmers to explain low-level technical details of a system while simultaneously providing the context of how those details fit into the broader architecture. It lets programmers document code in the same way that they would explain it in person: by walking the consumer step-by-step through the important parts of a codebase.
A tour is a series of locations throughout a codebase, along with accompanying prose that explains the importance each location in turn.
A maintainer of a project can more effectively introduce newcomers to the project by setting up one or more tours for the codebase that highlight the relevant functional components. A person implementing a complex feature or workflow can use a tour to solicit feedback from other people who are familiar to the codebase, but not that particular logical flow.
To create a new tour, start off by creating a separate directory (versioned with git if desired) that will hold your tours. You can use this to keep track of lots of tours of lots of codebases at once.
From the command palette (
Now, you can go from file to file, adding tour stops by right clicking on lines in code and selecting "Add a tour stop" from the context menu. Once you create a stop, you can add a markdown body.
Opening a Tour from Someone Else
If someone else provides you with a tour, there are a couple of steps that you need to take before you'll be able to actually view the tour.
First, make sure you have any repositories that the tour visits checked out
on your machine via git. For example, if the tour touches
Then, run Tourist: Map a name to a repository from the command palette and
show tourist where you put each repository on your system. By convention, the
tour file will use the plain repository name (e.g.
Now you can run Tourist: Start a tour to view the tour!
Optionally, you can also turn on "Read-only Mode" by unchecking "Show Edit Controls" in the tourist user settings.
This project is a Visual Studio Code plugin. In order to run the plugin, open the top-level directory in VSCode and simply run the debugger.
A new editor window should open with the Tourist extension running!