Onboarding can be challenging for any team, especially when documentation is scattered across multiple systems. A new team member is left to navigate through hopefully-complete lists of links to wiki docs, internal videos, sequence diagrams, open source projects, and more. These lists often come in the form of improvised training decks in slides that are outdated by the time the next person needs to onboard.
Swimm has a solution to this problem, and it’s as obvious as the wheels on the bottom of a suitcase: Documentation Playlists.
Playlists are one of Swimm’s most popular and frequently discussed features because they’re one of those “why didn’t anyone think of that before?” solutions for how to walk developers through your codebase.
What is a Documentation Playlist?
A Swimm Playlist is just what it sounds like: a collection of documents, links, videos, Markdown files, and images stored as a Playlist collection in a particular order. Playlists live right inside the code repository. Changes are tracked with Git with all the benefits of commits and branches. Swimm keeps track of progress in a Playlist, so you don’t have to remember where you’ve left off.
As developers, we know that repository structure can change over time and developers are often working on more than one repository. Swimm Playlists can help you step through documentation that spans one or more repositories. You can be sure that your docs are up to date in your current branch or the default repo branch because Swimm Docs contain live code snippets.
Documentation Playlists are Markdown files
Behind the scenes, Playlists are Markdown files that live in a code repo’s Swimm Docs folder. They’re stored with the .pl.sw.md file extension and are human-readable, meaning they can easily be edited within your IDE or reviewed in Pull Requests in GitHub.
Accelerate onboarding and ease offboarding with Playlists
Onboarding new team members with a Swimm Playlist is the most straightforward and powerful use case. At its heart, Swimm is a new knowledge operating system for your code, emphasizing knowledge sharing. This means, for example, that team leads can log into Swimm’s web app and put together technical onboarding Playlists that are customized for their team’s specific needs.
Playlists are very easy to maintain in terms of ensuring that the onboarding process is up to date. All you have to do is to add, order, and remove steps as needed. For example, when someone creates a new doc with important information for everyone on the team, you can add it to an Onboarding Playlist so that new team members won’t miss it. And then Swimm keeps all the docs in your Playlists up to date for you.
Playlists are also essential for offboarding. The departure of a key employee is the main reason code becomes “legacy,” which is why it’s so important for an offboarding employee to review code, Playlists, and resources to ensure their tribal knowledge isn’t permanently lost.
Other use cases for Documentation Playlists
At Swimm, we use Playlists in various ways: training, runbooks (including our on-call support rotation), and as a way to organize information. We also put Playlists within our Playlists for more complex knowledge sharing.
Our Playlists are organized and contain summaries of key points and takeaways wherever possible. We see our customers use Playlists in novel ways too.
Here are some examples:
- Product and feature planning: Create a Playlist for a large feature that includes all the requirements. During the development, developers can add or edit docs with technical decisions during the planning, designing, and development about why particular decisions were made. Playlists are used to document the reasons so the thought process won’t be forgotten.
- On-call process: Ensure the latest procedures are followed in light of known issues and lessons learned for incident resolution.
- Variable and parameter tracking: Use code snippets to track the origin and evolution of individual tokens, variables, parameters, and more throughout a workflow (even across multiple repositories). This is another useful way to organize your docs in your repos.
Documentation Playlists are easy to use, peruse, and maintain
Creating a Swimm Playlist is a single click away in Swimm’s web app. Once created, adding an item is easy with our point-and-click contextual interface. Playlists can use any external link, or pull directly existing documentation in the repo making it easy to link to docs and Playlists across multiple repositories.
How to create new Documentation Playlists
New Playlists can be created by clicking on “Playlist” to create a collection of docs.
Our Playlist Step browser shows docs from all your repos in your Swimm Workspace. Drafts can be found here as well if you want to edit your documentation as you build your Playlists.
How to add new items to a Playlist
To create new documentation for your Playlist while inside a Playlist, you have a bunch of options: start from scratch with blank docs, add existing docs, or use templates, or Swimm Generated Docs.
When adding items to a Playlist, it can be helpful to know whether the doc is in a draft state or if it’s been committed to the repo. Swimm clearly lists the stage of the Playlist item whenever it’s applicable, and any Playlist in any stage can be previewed in the web app.
You can add existing docs to the Playlist that are in a selected branch, or create new ones as part of the Playlist and then edit the existing docs and commit everything together.
Updating a Playlist is literally drag-and-drop within the web app. Every item in a Playlist has a visual indicator icon for its type (e.g., doc, Playlist, link), which makes it easy to identify what is being moved and where. Click the plus (+) sign to add links, units, docs, videos, and also create new docs while working on a Playlist.
How to publish Playlists
Because Playlist files are stored as code within the repo, any saved changes are subject to GitHub’s pull request features. Users can push a Playlist change directly to a known branch or create a new branch.
It’s also easy to look at previous versions of a Playlist to see what’s been added, changed, or removed using Git features.
Finally using the pull request feature during code review, reviewers can easily comment on the Markdown of the Playlist and either approve or request changes.
How to see your progress in a Playlist
Once a Playlist is created and used, progress is automatically saved for each user and visualized by an indicator in the Playlist navigation area. When a Playlist is completed, it gets marked as “done.” No more wondering where you’ve left off.
Anyone already familiar with the material in a Playlist can mark an item as “watched,” which will track progress through to the next step of the Playlist.
Finally, if a Playlist needs to be deleted, it can be easily done in the Playlist menu browser by creating a commit with the deleted Markdown file. The old file will still be available if you navigate to an older commit for the Playlist.
Bottom line
Documentation Playlists are the best, most accessible, and most intuitive way to present an ordered collection of docs to share and communicate that knowledge across a team. In addition to Playlists, Swimm allows documentation to be viewed and linked with tags and folders, but for docs to be consumed in a particular order, there’s no beating a Playlist.
Whether onboarding a new employee, offboarding someone with key tribal knowledge, or prepping for an on-call rotation, there are many ways to use a documentation Playlist effectively. And because Swimm tracks progress through a Playlist, no one will get lost in a sea of links in a slide deck.
If you are interested in helping engineering teams sync with code by integrating Continuous Documentation into the development workflow, sign up for Swimm or request a demo.
