Make the Thing a Link

A quick way to level up prose.

August 31, 2023 • 3 min read

Links rock.

An awesome habit when writing – for example, in a Slack message or doc – is to add a link to the thing you’re talking about.

We’ve updated the Octopus Report, which you can find here. Feedback is due by Friday.

Cool. Now people don’t need to hunt down the thing. They’re more likely to act, and your efforts on the report are more likely to be seen.

Even better, though, is this:

We’ve updated the Octopus Report. Feedback is due by Friday.

The thing itself is a link. Delightful. Skimmable. When you see the thing, it’s clear you can get to it. When you see the link, it’s obvious it goes to the thing. Want to find the thing? Look for the name of the thing. ⭐

Thing-linking benefits all readers, but it’s especially good for accessibility. As most accessibility guidelines note, screen reader users often navigate from link to link, and hear just the link text. You want those folks to hear “Link: Octopus Report.” instead of the dreaded “Link: here.”

So we want to link the thing, but sometimes “the thing” is not a noun. Often, it’s a verb – a call for action. A tired page might say:

To keep more than 3 octopi, a Q4237 form is required to be filed on this Central Services page.

What is the thing that matters here? A Central Services page? The cephalopods? No, it’s filing the form. The thing you link, in any given text, should describe the user’s intent. So let’s level that up:

To keep more than 3 octopi, Central Services requires you to file a Q4237 form.

Great. Now, if you’re unlucky enough to need to file that form, your eyes and pointing device immediately jump where they need to go.

Even for writers well-practiced at link formatting, there’s a gremlin that occasionally sways things back towards bogus link text: SEO.

While the primary duty of links is to serve your readers, occasionally you need to concede that the world revolves around Google, and sometimes Google won’t associate public pages with certain search terms unless it’s seen those terms in inbound link text.

For example, people might mention that they’ve searched “(your name) podcast” in an attempt to find your new show but it doesn’t come up – hypothetically that is. In this case, you might be tempted to create some links to the show labelled not with the show name, but with the search term. In other words, degrade your prose for the algorithm.

While sometimes this can be pragmatic, it’s worth trying your best to keep it natural. Maybe you go for a bit longer link, with both the desired keywords and the destination thing, e.g. “Allen Pike’s interview podcast, It Shipped That Way”. For example.

The thing to remember is that link text is UI. If it’s just in an internal doc or an email, it might be low-stakes UI, but it’s still worthy of consideration. So next time you refer to a resource, a doc, an issue, or some other thing your reader might care about, take a moment – and make the thing a link.

Latest in the series Writing.

Liked this? Follow along to see what's next.

© Allen Pike. 👋🏼 You can contact me, or check out Steamclock.