Tip 29 - seen and not heard

Jul 22, 2024

Often when we write, we use styles like bold or italics to convey the way our sentence sounds in our own head. This helps us ensure that readers get our meaning, and often that they also get a taste for our personal voice and style. Word emphasis make or break understanding a sentence… or a writer!

Ideally, documentation doesn’t need this same kind of reliance on the writer’s voice to guide you through the text. This is just one more reason to favour shorter, “boring” sentences.

One PR suggestion I will make is to visually mark the entire idea you want to get across, not just the individual words that may affect how the sentence is understood. For docs, I prefer to rewrite so that these style markers aren’t necessary in the first place. But, if you are going to call inline attention to a word or phrase because it’s that important, then optimize for the readers who are skimming your page.

✅ If an existing page file exists, Astro will not redirect to another page.
😐 If an existing page file exists, Astro will not redirect to another page.
✅ Astro leverages server-rendering over client-side rendering in the browser as much as possible.
😐 Astro leverages server-rendering over client-side rendering in the browser as much as possible.

Consider what your reader will see when skimming your inline styles, and what information you are really conveying to them. What will a reader take away if “not” is all they see? And, if my sentence depends on being read it in exactly one way, then maybe I need to reconsider how clear it really is. 😅

Fun fact: links automatically include their own inline styling. Sometimes, I’ll realize that I’ve previously written about the idea I want to emphasize. Using links to emphasize may not recreate my personal, super cool style. But, default link styling will catch a reader’s attention and can help me suggest a particular rhythm or flow in a sentence. At the same time, you’ve given your reader helpful context if they’d like to explore more about why this might be an important idea!

See the whole list of tips!

Toggle Comments