Tip 41 - if you please
Docs writing often addresses the reader to avoid clunky sentences or passive voice. When writing instructions, letting your reader know what “you will see” can be helpful and reassuring as they work through your guides. Docs is, though, a one-way broadcast.
Writing your docs to your readers doesn’t mean you have to follow conversational conventions. You can respect your readers without being “polite.”
One PR suggestion I will make is to remove formalities and pleasantries when I’m not soliciting or recognizing particular action. We typically don’t “thank” our readers at the end for completing our guide. (Though, we may thank visitors for expressing an interest in contributing when they land on our Contributing guide!) It’s just as out of place to preface instructions or explain features with “please.”
- ✅ Adding the official Astro MDX integration allows you to write standard Markdown with JSX variables, expressions and components.
- 😐 Please install the official
@astrojs/mdxintegration to use JSX variables, expressions and components.
No, I’m also not a fan of “Please see the view transitions guide for more information.” I am not asking them to go there. I am informing them that there is more information available. “Please” implies a request. Or, it is overly formal/flowery language that doesn’t belong in our docs anyway.
I try to make Astro docs as full-service as possible. If I’m doing it right, I shouldn’t need to “ask” you to do anything. Just sit back and enjoy the docs!
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 
