Tip 22 - and then
We all agree that in most situations, most of the time, āless is moreā when it comes to writing. For content-heavy contexts like docs writing, itās always a struggle to provide enough information while sticking to this adage. We want our readers to have alllll the information they could possibly want need to be successful!
One PR suggestion I often make is to start by deconstructing separate ideas into their own sentences ruthlessly. A little bit of sentence variety is fine, and can even make prose easier to read. But starting from the smallest possible building blocks ensures that I am building back up intentionally.
Paradoxically, āmake shorter sentencesā often meansā¦ āmake longer sentences!ā š You may need to add words to provide context you might have lost by turning a phrase into a full sentence. I find that āover-zealous choppingā + āreintroduce contextā can often get me pretty close to readable docs:
-
ā These features require some one-time code set up. After that, your site will automatically update in response to changes. Astro will rebuild a new version of your site each time using both the current files in your project and any data returned by the most recent fetch calls.
-
š These features require some one-time code set up, then will re-run at build time and return updated results based on the current files in your project and any data returned by the most recent fetch call.
Another advantage to splitting and recombining ideas: it can be easier to spot a better (re)grouping of these ideas than you originally had. Docs isnāt a jigsaw puzzle with only one correct spot for each piece! Docs is maybe more like a Scrabble rack of tiles: individual letters you position and reposition in search of a good word to play.
As with any tip, your mileage may varyā¦ just like your sentence lengths! But, Iām often pleasantly surprised that the ālongerā shorter sentences end up improving the readability and flow of the entire paragraph. At the same time, my āshorterā shorter sentences can be direct and punchy. In both cases, itās easier for me to intentionally control the flow of information to my reader.
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