Last week I talked about developer waypoints and said that even in open-world games, designers intentionally guide players to parts of the world on purpose. They do this by creating "quests" (in RPGs, at least). A quest has a narrative that provides the motivation as to why.

Medusa.js has done the same thing in their docs, guiding developers along narratives using Recipes and Paths.

Here's how it works.

Once you get past the getting started tutorial ("Time to hello world"), the next step is to get something done ("Time to value"). At the end of the getting started guide, Medusa directs developers to their Recipes page:

Note they are also capturing data on whether or not the GSG was successful

Recipes are oriented toward the broader context: what do developers want to accomplish with Medusa?

Medusa Recipes | Medusa
This document provides you resources for different paths based on what you’re building with Medusa.

You then pick a path, like Setup Ecommerce Store.

Once you click "Start Path," a widget pops up in the lower right and jumps to the first docs page in the path.

Pinned down to the bottom right

Here's why it's awesome: these are not custom path pages. These are existing pages in the docs that have simply been assigned to a "path" – a guided tour. A quest.

When you finish the docs page, click Next to move to the next step. Or don't! The developer has agency as to whether they want to continue or if they got what they needed.

Once you're done – guess what? You can provide feedback (collect data!) that I'm sure the team will use to improve the learning experience over time.

There are a few things I love about this:

Basic Gamification

It showcases a very simple gamified experience through progression tracking. There's a reason why you are compelled to remove the red dots on your home screen – it creates an open loop and we have a lizard-brain desire to close that loop. This is what most gamification is predicated on.

You Don't Need an Account

Learning path data is stored in browser local storage

The learning path feature is simple and doesn't require a login, implemented using plain old browser APIs like local storage (their docs are built on Docusaurus).

Here's the code to implement the Learning Path logic using React.

They Are Gathering Actionable Data

Most docs sites are static – there's no feedback loop to help improve the learning experience for developers. Medusa solves this by adding a few frictionless data collection points that can be fed back to their docs team. Not only that, by capturing this data they are getting to know the paths and ways developers take through their docs.

I love, love, love this, and I hope documentation learning paths make their way into more dev tool docs sites.

Have a lovely day,

Developer waypoints, part 2: Learning paths

Want devs to love your product?

Hi πŸ‘‹ I'm Kamran. I'm a consulting developer educator who can help your DevRel team increase adoption with better docs, samples, and courseware.
Sign up