Tip 35 - link in bio

Jul 28, 2024

Inline text links are an efficient way to provide readers with optional extra context at the moment they encounter potentially unfamilar content. Many documentation sites link liberally to help readers discover and navigate to related content.

Links to source material also allow us to write content once (or, in the case of external links, not at all!) to reduce our maintenance burden and provide a single source of truth. Links directly within our text signals to our readers that there’s more about this elsewhere if they need it, without cluttering the page with “Read more about…” throughout.

However, links are distracting:

Where a footnote gives your brain a gentle nudge, the link gives it a yank. What’s good about a link – its propulsive force – is also what’s bad about it.

— Nicholas Carr, Experiments in delinkification

One PR suggestion I’m often making is to remove linked text when I feel it’s more helpful to keep the reader following the current page’s flow. Like many edits, this is a judgement call. However, there are some standard situations where it’s helpful to support reading without interruption: following instructions, being introduced to an entirely new concept, or anything else where the reader might need to focus or may already be holding multiple concepts in their head.

✅ How do islands work? By default, Astro will render every UI framework component to just HTML & CSS, stripping out all client-side JavaScript automatically.
😐 How do islands work? By default, Astro will render every UI framework component to just HTML & CSS, stripping out all client-side JavaScript automatically.

We paid particular attention to our linking when writing the Astro introductory tutorial. This tutorial was designed to be accessible to learners who may never have used common web development tools such as VS Code and GitHub, and who have never deployed a website. Reducing distractions and helping them progress through the instructions is incredibly important in this kind of situation!

Don’t make your readers fight the temptation of the visual decoration that links provide which contains the promise of something more! (What is at that link??)

Readers also don’t know whether you intend for them to click a text line right now! (You put it there, after all.) It can be interpreted as an indication that you don’t think they’ll understand what comes next. And if they find inline links on that page, who knows when they’ll get back to the content they originally came to read?

See the whole list of tips!

Toggle Comments