Tip 13 - inadvertently inappropriate

Jul 6, 2024

While “like” often doesn’t convey enough information, some words convey too much: another meaning or nuance that you don’t intend. And if you’re super lucky, you might encounter a word that does both!

One PR edit I make is to remove the word “appropriate” from documentation. This unicorn word is both not descriptive enough and has a particular unintended suggestion that I prefer to avoid in Astro docs. What a find! Gotta give it up to “appropriate” for being “inappropriate” on multiple levels.

✅ “Any supported page file (.astro, .md, .mdx, .js/.ts, .html) located within src/pages/ automatically creates its own page route on your website.”
😐 “Any appopriate page file (.astro, .md, .mdx, .js/.ts, .html) located within src/pages/ automatically creates its own page route on your website.”

As an adjective, appropriate just means “suitable.” Like “like”, it doesn’t tell you how it is suitable. And “suitable” in docs often means “works.” This is yet another example of asking your reader to have your context and infer the correct connection that you, the writer, are making. This particular configuration or use works because… why? I never want my reader to have to read my mind to figure out what exactly I mean.

But things get interesting when you consider the meaning of “inappropriate.” This word is most often used to convey a judgement about what is or isn’t “proper.” The word “inappropriate” is often used as a synonym for “(slightly) offensive.” (“That t-shirt is inappropriate for this event.”) I prefer not to suggest that my readers might actually be causing offense with their not-yet-properly-working code!

While I do often vary my language by using synonyms because presenting the same things said in different ways can be an effective form of repetition as a pedagogical technique, I am also always on the lookout for any unintended messages.

See the whole list of tips!

Toggle Comments