Tip 38 - this and that

Jul 31, 2024

Docs is fact, not fiction. There’s no story arc, no conflict, no twists and turns. You’re not trying to surprise your reader… unless you count surprising them with how great your docs are! 🙌

Readable docs follow a straight, predictable, boring path. I’m usually trying to remove complications and contradictions, not highlight them.

One PR suggestion I will make is to try replacing “but” with “and” to see whether you can join ideas in a more neutral way. If it fits, it sits! “But” conveys to your reader that the relationship between two ideas is somehow unexpected, surprising or contradicting. And usually, our stories just aren’t that interesting. Furthermore, now they have to process the two pieces of information you wanted them to know and a (perhaps errant?) third concept: why these two ideas are in conflict with each other.

✅ Your original image will be copied unprocessed to the build folder, and Astro’s image integration will also return optimized versions of the image.
😐 Your original image will be copied unprocessed to the build folder, but Astro’s image integration will also return optimized versions of the image.

If they both work equally well, the tie goes to “and” because it evokes… absolutely nothing at all! “But” holds the promise of something different, interesting, challenging. “But” brings the popcorn. “And” hands you a glass of tepid tap water.

Of course, don’t be afraid to use “but” when there really is something contradictory or unexpected between two ideas you’re joining together. Sometimes it’s the right word for the job in that sentence! But, I also want to make sure that I’m not the one overcomplicating things by putting those ideas together in the first place! 😅

I find that too many “but”s in my writing could be a sign that I’m bouncing back and forth between disjointed thoughts. Maybe I can find a better way to combine them so they flow from one to the next without taking that hard turn.

You can take advantage of your “captive docs audience” — you don’t have to keep them on the edge of their seat. They won’t lose interest and leave if you’re not complelling enough. They want “just the facts” and “none of the drama.” Can I refill your glass?

See the whole list of tips!

Toggle Comments