Tip 27- writing that clicks

Jul 20, 2024

You might be familiar with the advice to not use “Click here!” as text for your links. This is an accessibility issue because the link text, available to readers through assistive technology, has no meaning out of context. It doesn’t tell them anything about what the link is, where it goes, or why they might click it.

That’s a great tip on its own! You should follow it! I don’t claim to be an accessibility expert though. So, I hesitate to give you accessibility tips. I can tell you why I don’t like using the word “click” as a writer, however, and that’s where today’s tip comes from!

If you participate in the Astro Discord, you’ll see some… interesting “typos” from me. Depending on the device I’m posting from, I might be posting via stylus input, voice dictation, a trackpad, a mouse, or even my brand new little six-key USB micro shortcut keyboard with dedicated keys for cut, copy, paste, find, select all, and save.

If I’m dictating posts into my phone, then you’ll see a lot of “ducks” and “docks” instead of “docs.” If I’m handwriting, then you’ll see “does” (because handwriting keyboards favour the letters they think you wrote over autocorrect for sensible meaning). It is not safe to assume that I’m “clicking” anything!

And, with so many of our readers not just reading, but full-on programming, on mobile devices now (waves from 14” Samsung Galaxy Tab S8 Ultra), you don’t know which physical actions your readers are actually performing. If your user isn’t “clicking,” then prompting them to “click” is inaccurate.

One PR suggestion I often make is to guide your reader through a UI (user interface) using the site’s information hierarchy instead of assuming which input method they’re using.

✅ If you don’t have any API keys, create one by selecting **Add API key**.
😐 If you don’t have any API keys, create one by clicking in **Add API key**.

Full disclosure: I’m as much “that reader” as I am “that writer.” I will totally get taken out of the moment if you tell me to “click” when I’m not actually clicking. I like to think this is what makes me a thoughtful and empathetic docs writer! (Hashtag-lies-we-tell-ourselves?)

Some of your readers are clicking, but some are tapping. Others are pressing. And if I’m using your project? Hoo boy… all bets are off! 😅

There’s no guarantee I haven’t trained a crow to topple a set of dominoes that eventually sends an electrical pulse and updates my project settings. Decouple the physical action from the structural path you want your reader to take, because birds are smarter than you think!

See the whole list of tips!

Toggle Comments