Tip 5 - don't let the easy edit distract you

Jun 28, 2024

Astro Docs has over 1000 community contributors! And, I review most of their English contributions. With such a large, active population submitting content, we get submissions that regularly contain many of the common spelling and grammar mistakes you’d expect.

Experienced writers and editors can spot the wrong version of “it’s/its”, “there/their/there”, or “opt in/opt-in” a mile a way. These tiny mistakes are so common (we all make them!) and we are primed to see them when we’re reviewing. Sometimes in our haste to correct them, we run the risk of missing the “better edit.”

These fixes are important! Little inaccuracies in your text can undermine your readers’ confidence in the accuracy of your documentation. Noticing these errors distracts your readers. And, it can distract you while you’re editing.

This tip is for the reviewing stage: Don’t fall for the feeling of of having edited when you’ve only “fixed.” Would the contribution have passed your review if it didn’t need “fixing?”

😐 “For more information about the supported options, how to get it ~~setup~~ set up when using Prettier inside VS Code ‸, and more, see the plugin’s README.”
✅ “See the Prettier plugin’s README for more information about supported options, how to set up Prettier inside VS Code, and more.”

This is one way in which the editing stage differs from the writing stage. You can’t “unsee” what was put in front of you. As a reviewer, I will always be anchored by the existing text in front of me. When an obvious fix is grabbing my attention, I remind myself to correct it as a first step. Then, the review editing can begin!

See the whole list of tips!

Toggle Comments