"Links are the currency of the web."

That might be some kind of SEO proverb, I'm not sure but I swear I've heard it before.

It's true to some extent – cross-linking between blog posts and web pages helps search bots index your content and find connections. It's also a way to let people dive deeper into a specific topic.

But here's the problem when it comes to developer experience...

Every link is a potential avenue for a developer to go off the rails and exit your nicely curated experience.


Because every link is a question.

Should I click on this? Is it important? What am I missing?

Developers are curious, possibly more than anyone else, so they will click the links you give them. And once that happens, all bets are off, you're no longer in control.

Within docs, tutorials, and how-tos, there are only a few places I try to include links: at the start and at the end.

The start may need prerequisites and setup instructions (download this SDK, sign in). The end might link to further learning, or to the next course, etc. But in between? Try not to include any links. Instead: popovers, tooltips, modals, or other in-context UIs could be used to keep people within your experience.

You want people to finish the tutorial, not get distracted and end up on /r/AmItheAsshole for the 19th time that day.

Have a lovely weekend,

Every link is a potential distraction

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