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 
