8 ms·

I’m working on a tool that allows developers to record and playback interactive, guided walkthroughs of a codebase, directly from their editor. It’s called Code

I’m working on a tool that allows developers to record and playback interactive, guided walkthroughs of a codebase, directly from their editor. It’s called CodeTour, and it’s currently available as a VS Code extension: https://aka.ms/codetour https://aka.ms/codetour. I built it because I frequently find myself looking to onboard (or “reboard”) to a project, and not knowing exactly where to start. After speaking to a bunch of other developers, I didn’t seem to be alone, so it felt like this problem was deserving of some attention. While documentation can help mitigate this problem, I wanted to explore ways that the codebase itself could become more explainable, without requiring unnecessary context switches. Almost like if every repo had a table of contents. To make it easier to produce these “code tours” I built a tour recorder, that tries to be as simple, and dare I say, fun to use as possible. I’ve since found that this experience has value in a number of other use cases (e.g. simplifying PR reviews, doing feature hand offs, facilitating team brown bags, etc.), and I’m excited to keep getting feedback from folks as they try it out. It’s also fully OSS, so I’d love any and all contributions: https://github.com/vsls-contrib/codetour https://github.com/vsls-contrib/codetour.

petr25102018 7y ago
Looks really cool.
jolmg 7y ago
That's a surprisingly nice approach to the problem.
- lostintangent 7y ago
  Thanks! I took inspiration from the way I’ve seen some devs “document” their PRs: submit the PR, add a description, and then seed the PR with a handful of comments that call out the most relevant “markers” for reviewers to look at. I’ve always liked that approach, and thought it could be cool if you could do the same thing for any body of code (not just PRs!), and also enable the comments to be ordered, so that the “tour” itself is entirely guided.
pezo1919 7y ago
Awesome. Please create it for Jetbrains IntelliJ platform. Software tools are trending, you can charge money for it. I'd like to use VSCode but Webstorm is just so much more ahead. Most people and companies (who use them) already pay for Jetbrain tools.
- wolco 7y ago
  Slightly behind now at least in terms of this plug-in.
- lostintangent 7y ago
  Thanks for the feedback! In addition to CodeTour, I’m in the process of building out a couple of other tools (see below) to support better team collaboration, onboarding and knowledge retention. So I’m focusing on VS Code first, and iterating on feedback, before tackling other editors. That said, any thoughts on the usefulness of these solutions is extremely helpful, as I prioritize my backlog. Note: Other side-projects on my journey to improve the holistic developer experience: 1. GistPad - Developer library for managing code snippets, documentation and interactive CodePen-like playgrounds. All built on top of GitHub Gists (https://aka.ms/gistpad https://aka.ms/gistpad) 2. Live Share Spaces - A virtual team room for connecting with other developers, and being able to seek and provide in-editor assistance in real-time (https://aka.ms/vsls-spaces https://aka.ms/vsls-spaces)
  - RhodesianHunter 7y ago
    Going to second the request to bring this to IntelliJ. Everyone I know at my current and previous jobs would use the hell out of this, but so much of JVM development is on IntelliJ now. Awesome idea!
    - lostintangent 7y ago
      Thanks! Out of curiosity: in the interim of having an IntelliJ client, do you think your team would use a browser-based client and/or integration that was built into GitHub? I’m working on this right now, and I just wanted to check with you on the applicability of that for your specific team.
hyperpallium 7y ago
Huge problem, interesting solution. It takes time to derive the high-level from the codebase. I guess, your walk-throughs would be similar to how I'd explore it myself - without the mistakes. EDIT it's documentation, so can get stale/out of sync as the codebase evolves (not a problem for PRs). Though high-level architecture/APIs rarely change. BTW In github, I keep expecting the text next to files/dir to be a comment explaining the high-level (instead of the most recent commit message).
- lostintangent 7y ago
  Trying to codify the “tour” that a developer would have to otherwise discover themselves, is exactly what I’m trying to help with. This just seems like such an important phase of learning, that is currently way too manual. Regarding the comment about tours becoming stale: when you record the tour, you can choose to associate it with a specific commit/tag/branch. That way, when someone plays it back, it will continue to make sense, even in the midst of minor code changes/refactorings. I’ve also been working on making the tour editing experience as simple as possible, so that as you need to revise the tour over time, it’s not too difficult to do. That said, any artifact that’s a derivative/compliment of code (e.g. documentation, tests), represents an additional “burden” to maintain. So I’m focused on trying to keep the tours “stable” enough to support learning, and reduce the cost to editing them, to hopefully support the continued investment. I’m semi-hopeful that there’s a nice balance here, that provides an enjoyable enough DX, coupled with the team’s motivation/benefits to retain and transfer such important knowledge. We’ll see how it goes!
  - hyperpallium 7y ago
    Seems flawless for the important niche of specific commits. I guess navigation uses VS Code to locate functions etc, so it's robust to superficial changes (like ctags for vim). Keeping docs in sync is a hard problem!... \tangent: maybe a tour draft, of execution trace of a typical use, filtered to only key api calls?
    - lostintangent 7y ago
archlight 7y ago
this is great idea. you need guided tour when you visit a museum as vast as louver
- lostintangent 7y ago
  The analogy of a museum tour was exactly what inspired the name! When you want to really learn about something, it’s hard to beat the value of a guided walkthrough, that can provide you with just enough focus, while still allowing you to explore ideas on your own.
the_arun 7y ago
This is pretty cool. Hope GitHub implements this idea!!
- lostintangent 7y ago
  Me too! I started this discussion with Nat Friedman (GitHub CEO), and I’m excited to see what can be done here. Any feedback/interest from the community might help make this a reality :) https://github.com/vsls-contrib/codetour/issues/10 https://github.com/vsls-contrib/codetour/issues/10
quacker 7y ago
Love it. This is such a good idea. The only limitation is that it's VS Code only. But, the JSON output means I could easily write a script to produce HTML that could be hosted for other devs to view.
- lostintangent 7y ago
  Thanks! I’m keen to explore integration with GitHub in the near future (https://github.com/vsls-contrib/codetour/issues/10 https://github.com/vsls-contrib/codetour/issues/10), in order to provide a browser-based “player”. That way, the knowledge in the tour isn’t limited to any one editor. That said, I wanted to record the tours in a simple JSON file, specifically to enable interop with other tools. I’d love to hear any feedback you have on the experience and/or the format!
  - strzibny 7y ago
    I would love to see it being available for GitHub/GitLab. Personally I use Sublime Text now.
fishooter 7y ago
Love the idea! Maybe a suggestion with the "bit rot" problem (getting out of sync with code). Code tours will likely cover the most important parts of the codebase, which should be well tested in large projects (and large projects are the ones that need the tours). You could link the comments to those tests, and if any of those tests are changed, you will be advised to take a look at the tour comment. These tests can be also discovered automatically, as there exist code coverage tools.
- lostintangent 7y ago
  Ah I really like this idea! Currently, a tour can be associated with a specific commit or tag, to enable it to be resilient to code changes over time (e.g. minor refactorings that don’t fundamentally change the value of the tour). That said, there isn’t a way to automatically know when a tour should be updated, after a significant enough code has changed. Being able to bind a tour to one or more tests is a really interesting idea, and something that I’ll try to explore this upcoming week. Thanks so much for the feedback here!
  - o-__-o 7y ago
    How would you associate with ruby tests vs go tests vs my random test library that doesn’t have a great framework?
    - lostintangent 7y ago
      Great question! I’m not currently sure :) I’ve been fairly deliberate about building CodeTour in a language agnostic way, in order to ensure it could be applied to any file type within a codebase. This is partly why I haven’t based the tour definition experience on code comments: https://github.com/vsls-contrib/codetour/issues/38 https://github.com/vsls-contrib/codetour/issues/38. That said, I’m trying to keep an open-mind when it comes to increasing tour resiliency, since it may require language/platform-specific solutions. I’m not sure. If you had any thoughts, I’d love to hear them! Another potential solution is to have a CI task, that could check to see how far the code has deviated from the original commit that the tour was recorded on, and notify you when the deviation crosses some threshold. Maybe that’s a terrible idea, but something like that would have the benefit of being language-agnostic. Lots of exploration to do here!
mokshjawa 7y ago
So awesome! Actually, working on something somewhat similar called Codeflow (https://usecodeflow.com/ https://usecodeflow.com/). Right now, we have a web app where people can create these walkthroughs/tours but wanted to ultimately create an IDE extension. Love what you've done thus far.
- lostintangent 7y ago
  Oh cool! Yeah, we are definitely kindred spirits :) I wanted to start with VS Code (in order to scratch my own itch), but I’m now working on a browser “player” and looking into GitHub integration (https://github.com/vsls-contrib/codetour/issues/10 https://github.com/vsls-contrib/codetour/issues/10). I love seeing other folks investing in this space. Thanks for sharing!
nsomaru 7y ago
Sounds like a great idea! I'd love to use this from the terminal with vim.
- lostintangent 7y ago
  I’ve never built any tooling for Vim, but I’m really inspired by the challenge :) Thanks for the suggestion, and stay tuned! Note: If anyone’s reading this, and has experience in Vim “extensibility”, I’d like to collaborate: https://github.com/vsls-contrib/codetour https://github.com/vsls-contrib/codetour
jph98 7y ago
For somebody who has to do "company" or "engineering team rescue", this is awesome and hugely important to me.
- lostintangent 7y ago
  I’d love to hear more about “engineering team rescue” :) Are you referring to being suddenly dropped into a project that needs help (e.g. because it’s behind s schedule), and having to quickly ramp up?
jamil7 7y ago
Very cool!
gizzlon 7y ago
Cool. Having this for open source projects would be great way to learn about that codebase and also programming and patterns in general.
- lostintangent 7y ago
  That’s my hope! I read a lot of OSS code, and so I constantly struggle with understanding how to get started. Assuming folks find something like CodeTour helpful, I’d love to get support for advocating it and bootstrapping the ecosystem with tours for popular OSS projects.
mk4p 7y ago
Definitely not alone - great idea
- lostintangent 7y ago
  Thanks! This HN thread has definitely provided me a major boost in confidence that this is a worthwhile problem to solve.
thepiratesailor 7y ago
Why can't you create a documentation file which explains the code and how to get started. Tell me an idea more simple than this
lukapeharda 7y ago
Awesome tool!

petr25102018 7y ago

Looks really cool.

jolmg 7y ago

That's a surprisingly nice approach to the problem.

lostintangent 7y ago
Thanks! I took inspiration from the way I’ve seen some devs “document” their PRs: submit the PR, add a description, and then seed the PR with a handful of comments that call out the most relevant “markers” for reviewers to look at. I’ve always liked that approach, and thought it could be cool if you could do the same thing for any body of code (not just PRs!), and also enable the comments to be ordered, so that the “tour” itself is entirely guided.

pezo1919 7y ago

Awesome. Please create it for Jetbrains IntelliJ platform. Software tools are trending, you can charge money for it. I'd like to use VSCode but Webstorm is just so much more ahead. Most people and companies (who use them) already pay for Jetbrain tools.

wolco 7y ago
Slightly behind now at least in terms of this plug-in.
lostintangent 7y ago
Thanks for the feedback! In addition to CodeTour, I’m in the process of building out a couple of other tools (see below) to support better team collaboration, onboarding and knowledge retention. So I’m focusing on VS Code first, and iterating on feedback, before tackling other editors. That said, any thoughts on the usefulness of these solutions is extremely helpful, as I prioritize my backlog. Note: Other side-projects on my journey to improve the holistic developer experience: 1. GistPad - Developer library for managing code snippets, documentation and interactive CodePen-like playgrounds. All built on top of GitHub Gists (https://aka.ms/gistpad https://aka.ms/gistpad) 2. Live Share Spaces - A virtual team room for connecting with other developers, and being able to seek and provide in-editor assistance in real-time (https://aka.ms/vsls-spaces https://aka.ms/vsls-spaces)
- RhodesianHunter 7y ago
  Going to second the request to bring this to IntelliJ. Everyone I know at my current and previous jobs would use the hell out of this, but so much of JVM development is on IntelliJ now. Awesome idea!
  - lostintangent 7y ago
    Thanks! Out of curiosity: in the interim of having an IntelliJ client, do you think your team would use a browser-based client and/or integration that was built into GitHub? I’m working on this right now, and I just wanted to check with you on the applicability of that for your specific team.

hyperpallium 7y ago

Huge problem, interesting solution. It takes time to derive the high-level from the codebase. I guess, your walk-throughs would be similar to how I'd explore it myself - without the mistakes. EDIT it's documentation, so can get stale/out of sync as the codebase evolves (not a problem for PRs). Though high-level architecture/APIs rarely change. BTW In github, I keep expecting the text next to files/dir to be a comment explaining the high-level (instead of the most recent commit message).

lostintangent 7y ago
Trying to codify the “tour” that a developer would have to otherwise discover themselves, is exactly what I’m trying to help with. This just seems like such an important phase of learning, that is currently way too manual. Regarding the comment about tours becoming stale: when you record the tour, you can choose to associate it with a specific commit/tag/branch. That way, when someone plays it back, it will continue to make sense, even in the midst of minor code changes/refactorings. I’ve also been working on making the tour editing experience as simple as possible, so that as you need to revise the tour over time, it’s not too difficult to do. That said, any artifact that’s a derivative/compliment of code (e.g. documentation, tests), represents an additional “burden” to maintain. So I’m focused on trying to keep the tours “stable” enough to support learning, and reduce the cost to editing them, to hopefully support the continued investment. I’m semi-hopeful that there’s a nice balance here, that provides an enjoyable enough DX, coupled with the team’s motivation/benefits to retain and transfer such important knowledge. We’ll see how it goes!
- hyperpallium 7y ago
  Seems flawless for the important niche of specific commits. I guess navigation uses VS Code to locate functions etc, so it's robust to superficial changes (like ctags for vim). Keeping docs in sync is a hard problem!... \tangent: maybe a tour draft, of execution trace of a typical use, filtered to only key api calls?
  - lostintangent 7y ago

archlight 7y ago

this is great idea. you need guided tour when you visit a museum as vast as louver

lostintangent 7y ago
The analogy of a museum tour was exactly what inspired the name! When you want to really learn about something, it’s hard to beat the value of a guided walkthrough, that can provide you with just enough focus, while still allowing you to explore ideas on your own.

the_arun 7y ago

This is pretty cool. Hope GitHub implements this idea!!

lostintangent 7y ago
Me too! I started this discussion with Nat Friedman (GitHub CEO), and I’m excited to see what can be done here. Any feedback/interest from the community might help make this a reality :) https://github.com/vsls-contrib/codetour/issues/10 https://github.com/vsls-contrib/codetour/issues/10

quacker 7y ago

Love it. This is such a good idea. The only limitation is that it's VS Code only. But, the JSON output means I could easily write a script to produce HTML that could be hosted for other devs to view.

lostintangent 7y ago
Thanks! I’m keen to explore integration with GitHub in the near future (https://github.com/vsls-contrib/codetour/issues/10 https://github.com/vsls-contrib/codetour/issues/10), in order to provide a browser-based “player”. That way, the knowledge in the tour isn’t limited to any one editor. That said, I wanted to record the tours in a simple JSON file, specifically to enable interop with other tools. I’d love to hear any feedback you have on the experience and/or the format!
- strzibny 7y ago
  I would love to see it being available for GitHub/GitLab. Personally I use Sublime Text now.

fishooter 7y ago

Love the idea! Maybe a suggestion with the "bit rot" problem (getting out of sync with code). Code tours will likely cover the most important parts of the codebase, which should be well tested in large projects (and large projects are the ones that need the tours). You could link the comments to those tests, and if any of those tests are changed, you will be advised to take a look at the tour comment. These tests can be also discovered automatically, as there exist code coverage tools.

lostintangent 7y ago
Ah I really like this idea! Currently, a tour can be associated with a specific commit or tag, to enable it to be resilient to code changes over time (e.g. minor refactorings that don’t fundamentally change the value of the tour). That said, there isn’t a way to automatically know when a tour should be updated, after a significant enough code has changed. Being able to bind a tour to one or more tests is a really interesting idea, and something that I’ll try to explore this upcoming week. Thanks so much for the feedback here!
- o-__-o 7y ago
  How would you associate with ruby tests vs go tests vs my random test library that doesn’t have a great framework?
  - lostintangent 7y ago
    Great question! I’m not currently sure :) I’ve been fairly deliberate about building CodeTour in a language agnostic way, in order to ensure it could be applied to any file type within a codebase. This is partly why I haven’t based the tour definition experience on code comments: https://github.com/vsls-contrib/codetour/issues/38 https://github.com/vsls-contrib/codetour/issues/38. That said, I’m trying to keep an open-mind when it comes to increasing tour resiliency, since it may require language/platform-specific solutions. I’m not sure. If you had any thoughts, I’d love to hear them! Another potential solution is to have a CI task, that could check to see how far the code has deviated from the original commit that the tour was recorded on, and notify you when the deviation crosses some threshold. Maybe that’s a terrible idea, but something like that would have the benefit of being language-agnostic. Lots of exploration to do here!

mokshjawa 7y ago

So awesome! Actually, working on something somewhat similar called Codeflow (https://usecodeflow.com/ https://usecodeflow.com/). Right now, we have a web app where people can create these walkthroughs/tours but wanted to ultimately create an IDE extension. Love what you've done thus far.

lostintangent 7y ago
Oh cool! Yeah, we are definitely kindred spirits :) I wanted to start with VS Code (in order to scratch my own itch), but I’m now working on a browser “player” and looking into GitHub integration (https://github.com/vsls-contrib/codetour/issues/10 https://github.com/vsls-contrib/codetour/issues/10). I love seeing other folks investing in this space. Thanks for sharing!

nsomaru 7y ago

Sounds like a great idea! I'd love to use this from the terminal with vim.

lostintangent 7y ago
I’ve never built any tooling for Vim, but I’m really inspired by the challenge :) Thanks for the suggestion, and stay tuned! Note: If anyone’s reading this, and has experience in Vim “extensibility”, I’d like to collaborate: https://github.com/vsls-contrib/codetour https://github.com/vsls-contrib/codetour

jph98 7y ago

For somebody who has to do "company" or "engineering team rescue", this is awesome and hugely important to me.

lostintangent 7y ago
I’d love to hear more about “engineering team rescue” :) Are you referring to being suddenly dropped into a project that needs help (e.g. because it’s behind s schedule), and having to quickly ramp up?

jamil7 7y ago

Very cool!

gizzlon 7y ago

Cool. Having this for open source projects would be great way to learn about that codebase and also programming and patterns in general.

lostintangent 7y ago
That’s my hope! I read a lot of OSS code, and so I constantly struggle with understanding how to get started. Assuming folks find something like CodeTour helpful, I’d love to get support for advocating it and bootstrapping the ecosystem with tours for popular OSS projects.

mk4p 7y ago

Definitely not alone - great idea

lostintangent 7y ago
Thanks! This HN thread has definitely provided me a major boost in confidence that this is a worthwhile problem to solve.

thepiratesailor 7y ago

Why can't you create a documentation file which explains the code and how to get started. Tell me an idea more simple than this

lukapeharda 7y ago

Awesome tool!