Skip to content

Tip 29 - seen and not heard

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!

Toggle Comments

Ā© 2021 - 2024 Sarah Rainsberger. Except where otherwise noted, and/or quoting external sources, the content of this site is licensed under CC BY-NC-SA 4.0