Tip 16 - read this tip... if you want to

Jul 9, 2024

When I’m writing documentation, I may have some idea of what our reader “wants” to do. Sometimes, I don’t. Yet, I still have to produce guides and instructions that work in, or can be applied to, a variety of situations.

One PR suggestion I’m often making is to remove qualifying statements about the readers intent and replace them with direct ways to achieve a goal. I can’t be inside my reader’s head (no matter how much I might try or think I can… just me?). So, one of the specific ways I can safely cut extra words and tighten up my writing is to not try to be a mind reader:

✅ “To dynamically create an index.html at root level (e.g. for content fetched from a headless CMS), include an object with slug: undefined in your getStaticPaths() function.”
😐 “If you want to create an index.html dynamically at rool level (e.g. for content fetched from a headless CMS), you have to provide undefined as value for the slug to getStaticPaths().”

Like most rules, there are exceptions! I can picture myself consciously choosing this wording if I want to emphasize this action as a choice. (In my head, I’m hearing the stress on the word “want.” And, I’ve probably typed then deleted “really want.“) But, this is not my go-to style.

And, whether or not your reader “wants to” to do something doesn’t change the truth about how your project works. Be on the look out for “if you want to” followed by a description of your project that stands on its own: “If you want to use content collections, they will provide typesafety and autocomplete in your code editor.”

Don’t use, “If you want to” as a stand in for “Here’s why you might want to.” If you do make it about “you”, then keep it about “you!” But most of the time, I don’t need to play mind games with my reader at all.

See the whole list of tips!

Toggle Comments