Tip 34 - show what to do
If youâve been following this series of tips, you may have thought that my examples of âpretty goodâ (â ) vs. âmehâ (đ) for each of these tips are in an unintuitive order. And Iâll admit, sometimes it feels a little odd to me, too!
Itâs very common to show the âwrongâ thing, then correct it. But, I am a strong supporter of âshowing positive models.â Often in Astro Docs, you wonât even ever see the âwrongâ way to do something! Why would we put that in our docs?
Thereâs a good reason for that: how do you become a better writer? Read quality writing so you can internalize patterns to use in your own writing. What this means for docs is showing the âgoodâ version and not the âbadâ version so that you donât inadvertantly introduce, or reinforce, unwanted patterns.
One PR suggestion I am often making is to avoid showing anti-patterns in favour of showing positive models. In these tips, it means showing what I consider helpful documentation first, and only after that, showing a âless-optimalâ version of documentation. (In my mind, the âwrongâ way should seem so obviously less helpful in compmarison to what you just read that you would never consider doing that. Itâs always shown in relation to something better.)
I even considered not showing the âbeforeâ of the PR edits here at all! I want to share helpful models, and my strategy has been âshow an example of my tip in action first, and only then, show something that you can perceive by contrast isnât as helpful.â
-
â
<script>...</script>
-
đ â This doesnât work! â
<button onClick={handleClick}>Nothing will happen when you click me!</button>
Sometimes it makes sense to document what your users are naturally (and mistakenly) doing as a âWhat not to do.â But, if they werenât going to do that in the first place, why put that idea in their mind?
If your readers constantly struggle with something they expect to work, then it can make sense to call out that this pattern is not supported. But, my instinct will always be to present things in the positive: this is how Astro works, and this is how you do this in Astro. The less attention I give to things that donât actually work, the better.
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