Skip to content

Tip 1 - "... if one does not already exist"

Astro Docs publishes a lot of guides from community contributors that involve connecting with a third-party service such as a CMS or deploy host. This can mean instructing the reader to add files for environment variables or other necessary “glue” to connect the services, or to ensure the project contains a specific folder.

One PR edit I am often suggesting is to append any such instruction to create a new file or folder with, “if one does not already exist.” If this is something that might reasonably already exist in someone’s project, then it’s helpful to acknowledge that and assure the reader. This also demonstrates reader empathy by showing you have put a little thought into what their project might look like, and earns reader trust with your attention to a small detail.

At this point in their guide, they may very well be struggling with two platforms that they may or may not know well. Every little bit of assurance that they’re on the right track is some friction removed from their journey!

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