Back
blog

Swimm Universal Playlists - As Code Coupling For Continuous Documentation

Swimm Universal Playlists - As Code Coupling For Continuous Documentation cover image

Swimm’s “Playlist” feature is one of the most used and frequently mentioned features in describing Swimm to someone that hasn’t heard of it before.

What is a Swimm Playlist?

A Swimm Playlist is just what it sounds like: a collection of documents, links, videos, Markdown files, and images that you put into a Playlist collection in a particular order intended to help facilitate the onboarding of new developers. Swimm keeps track of what you’ve covered in a Playlist so you don’t have to remember where you left off.

And because the tide and currents churn many puns in the Swimm HQ sea, of course, they began as something along the lines of lanes, and were far less advanced than they are now. It’s fascinating how iterating over such a simple concept became one of our most-loved cornerstone features.

The most common and earliest use of a playlist was stepping through documents in a single repository, and then ultimately through multiple repositories. Playlists now provide not just the ability to step through code paths that span multiple repositories, but also as universal ways to bridge learning paths together.

Using Swimm’s Playlist for onboarding and offboarding

Using Swimm’s “Playlist” feature is a very simple but powerful approach to onboarding new Swimm users. Also, many of our early adopters have shared that it’s an equally beneficial approach to offboarding by identifying areas where special care should be taken to reduce knowledge leaks.

Now, if your onboarding process involves generating some kind of path for the new hire in LinkedIn Learning (or similar online learning platforms), you can also use Playlist links that should go along with their role.

HRIS (software your people team uses) can be taught about playlists in a variety of ways, depending on the software and the need.

Hackathons, Bootcamp Kickoff, Sales Engineering Training, CS Training

Organize playlists with summaries of key points and takeaways for a variety of perspectives. Help sales engineers understand what’s being undersold in the current marketing materials through high-level walk through documentation, or lay out the possible projects for hackathons or cool down cycles.

Sprint Planning

A big barrier to Continuous Documentation is not reserving any time to bring things up-to-date in the sprint. While it’s not always necessary to carve out more than a few hours, it’s good to allow for it and take it back if you don’t need it. Playlists are a great way to start pointing at parts of the code that you’ll be working on next, and describing the outcomes. These playlists can later become the basis of the rest of the documentation you’ll need.

Your Use Case Is The Most Important One

If you thought of an interesting way that you could use a Swimm playlist in your workflow, that’s exactly what we hoped would happen. Swimm is language agnostic, which means we also have to try to be workflow agnostic and not impose constraints that aren’t absolutely necessary for the product to work.

Playlists are a great example of one loosely-coupled component that comes together with Docs, Smart Text, IDE Plugins and our Github App or other supported CI servers to form a complete package.

How Swimm Playlists Changed Shape Over Time

As mighty as Swimm’s initial playlists feature was, it had limitations just like everything else that’s within 200 commits of version-0 in early beta. We then launched plans to cover multi-repository cases while working on all of the plumbing and performance needed to make a single relatable object to create all kinds of learning path combinations.

Swimm’s `.swm.md` Format

Through many, many iterations of the Playlist feature, we finally condensed all of the functionality into a more performant universal format that sets a demarcation point away from a time where there were ever different types of playlists. Then, we deployed a change that implements playlists as-code on the back end, in our `.sw.md` markdown format. This allows for interesting possibilities in learning path creation:

Swimm’s Guided Visual Playlist Editor & Player

Swimm created an easy way to make changes to your Playlists with the Playlist Editor – all you have to do is click the plus sign to add in additional links, units, docs, and videos; you can also preview any Playlist.

Consuming (going through) playlists is just like reading other Swimm documentation, however you manage publishing it.

Bottom Line

Playlists help capture vital low-bus-factor details to create a seamless onboarding and offboarding – those transitions when you just need everything to be straightforward and easy.

If you are interested in helping engineering teams sync with code by integrating Continuous Documentation into the development workflow - so that docs are always up to date - checkout Swimm, and Swimm's free beta access.

It's been a game changer for dev teams.