lostintangent

I’d love to collaborate with you on this! I’ll take a look at your project later this evening, since it might point at some improvements I can add to CodeSwing. Otherwise, I’ll be on the lookout for an issue or pull request from you soon :)

Exactly! I'm a huge fan of CodePen/JSFiddle/etc., but wanted to have an experience that let me take advantage of my existing editor setup, in order to experiment with ideas or learn new things. I built CodeSwing to "scratch my own itch", and I'm keen to hear if it's useful for others as well :D

Regarding the Golang playground: is this what you're thinking about? https://play.golang.org/. CodeSwing is a general-purpose "interactive coding environment", and therefore, I'd love to expand it over time to include more languages. Right now, it's limited to web scenarios, but that's simply where I started.

Would it be useful to be able to create a new Go/Rust swing inside VS Code, and have it automatically run your code, and display stdout in a console window as you type? Or did you have something else in mind?

Ah, got it. Apologies for misunderstanding! I'm currently working on the ability to export a swing to CodePen and Bl.ocks, so that you can create your swings in VS Code, and then share them with the appropriate communities. I should have both of these done this weekend. Would that work for your workflow? Since you can export CodePens as gists, and all Bl.ocks are already gists, you can actually already open any CodePens/Bl.ocks inside of GistPad right now. So I just need to finalize the swing->CodePen/Bl.ocks experience.

Regarding GistPad: it bundles CodeSwing along with it (as an optional, uninstallable dependency), so that you can install GistPad and use it to create code snippets/swings/notes/etc. So CodeSwing is the core "interactive coding playground" environment, that can be used with or without GistPad. And GistPad is effectively a virtual filesystem for VS Code, that allows you to edit gists and repos as if they were always-available files.

That's on the team's near-term roadmap :) In order to build full apps/projects, having an editor-integrated browser preview will be amazing!

CodeSwing is really meant to enable component/snippet/sample development (like a "visual REPL"), so you can quickly try out, learn & share ideas, without needing to set up any build ceremony in order to get there. I'm hoping that it will be complimentary to a built-in browser preview in VS Code. But I'm keen to hear folks thoughts about it :D

Hey! By default, none of the current templates add any libraries to the swing. However, I'm planning on adding new template galleries to make it easy to create/explore ideas using popular frameworks. I'd love to hear if you have any suggestions for what you'd like to see me prioritize (e.g. React, Tailwind, etc.), since I'll be working on that this weekend :D

That said, when you create/open a swing, there will be a "CodeSwing" view on the Explorer tab, which displays all the files in the swing. One of those files will be called "codeswing.json", which is the manifest for the swing itself. If you click on it, you'll see two array properties, called "scripts" and "styles", which list the libraries that have been added to the swing. When you add a new library via the "Add Library" command, it will add the selected library to that file: https://github.com/codespaces-contrib/codeswing#external-lib.... Let me know if you have any feedback on that experience!

Regarding sharing: I maintain another VS Code extension called GistPad (https://aka.ms/gistpad) that allows you to login with GitHub and then manage gists/repos without cloning/committing files. GistPad has an integration with CodeSwing that allows you to create swings as gists, and then edit/share them with others: https://github.com/codespaces-contrib/gistpad#codeswing. Since GistPad shows your starred gists, and lets you follow other GitHub users, you can also share swings by simply starring/following others that are creating swings in gists.

Additionally, since you can create new swings as local directories (using the "CodeSwing: New Swing..." command), you could store a swing in a GitHub/BB/GitLab repo, and then when others clone and open that repo in VS Code, the CodeSwing extension will detect the swing and automatically launch the right coding environment. The gif in the project's README shows that in action using GitHub Codespaces.

Let me know if any of that sounds interesting, or if you have feedback on how I could improve the overall experience. Thanks so much for checking out CodeSwing!

That’s exactly what GitHub Codespaces provides: https://github.com/features/codespaces.

Thanks for the quick reply! Like I mentioned, I would gladly pay the annual fee right now, since NotePlan looks _very_ close to what I’m looking for.

But I’m pretty invested in using GitHub for my notes, and so I only need an editor to be an editor, not managing/syncing my notes.

I’ll keep an eye on NotePlan in the future. Awesome job on the app and congrats on the launch!

This looks awesome! I’d switch to this immediately, but there’s a couple things I’d love to confirm before downloading/paying for another app (I’ve tried nearly every MD editor on iOS!):

1. Does it support opening external folders from other iOS apps? I’ve started using Working Copy so that I can store and sync my notes in GitHub repos. I’ve been using iA Writer as my Markdown Editor (since it interops nicely with Working Copy), but I’m interested in something with better Roam/Obsidian-like features.

2. Does it have a Markdown preview? Or just the editor + navigation support? I often use a lot of Markdown tables, and so having a preview mode is pretty critical to efficiently reading the content later.

Out of curiosity: what are the primary reasons for your web preference?

Thanks for posting this! I’m the author of CodeTour, and would love to hear if folks had any questions/feedback.

Whenever I onboard to a new codebase, or try to learn more about an open-source project, I typically create personal notes that outline the structure and high-level “markers” that I want to remember and easily reference later.

Unfortunately those notes are disconnected from the codebase itself, and therefore, not as immersive/rich as I wanted them to be. So I created a tool that allows me to annotate codebases with my own walkthroughs/breadcrumbs/ToCs and then play them back at any time, directly within my editor. This workflow has provided a pretty nice productivity boost for me thus far, and has the benefit of enabling me to share these walkthroughs with others as well: https://github.com/vsls-contrib/codetour.

This is so awesome! I wonder if it would be useful to have this knowledge “overlayed” on top of the Svelte compiler source itself. That way, contributors could clone the repo and get an annotated tour of the compiler process, directly from their editor.

I’ve been working on a side-project, that allows recording and playing back interactive, guided walkthroughs of a codebase. This seems like an excellent “test case“ for that experience, which I might have to experiment with :)

https://aka.ms/codetour.

Thanks! If you get a chance to check it out, please don’t hesitate to send any feedback my way. I need all the help I can get in order to ensure this experience is awesome :)

https://github.com/vsls-contrib/codetour

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.

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!

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

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.

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.

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?

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

Ah OK cool, apologies for misunderstanding you. Now that I’ve got the core record/playback experience, I’m keen to explore ways to simplify the authoring and maintenance experience even further. Enabling a “code profiler” for recording/updating tours could definitely be really useful. Thanks for the feedback!

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).

I love seeing other folks investing in this space. Thanks for sharing!

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!

Thanks! I’m keen to explore integration with GitHub in the near future (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!

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

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.

I’d love to hear more about your thoughts on draft tours! Currently, you can record as many tours as you want per codebase, and so you could record one that was scoped to just key API calls, and have n-number of other ones with more detail, alternate flows.

Would that satisfy what you’re thinking? Or were you thinking about being able to record a tour, and mark certain steps as being more important than others? Any feedback here is unbelievably valuable!

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)

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)

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!

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.

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.

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.