RSS Validator Results: https://www.rainsberger.ca/blog/rss.xml

RSS Validator

This service tests the validity of an RSS 2.0 feed, checking to see that it follows the rules of the RSS specification. For advice from the RSS Advisory Board on how to implement RSS and handle issues such as enclosures and HTML encoding, read the RSS Best Practices Profile. This checker is also a validator of Atom and RSS 1.0 feeds.

Use this tester regularly to ensure that your RSS feed continues to work well in the wide audience of RSS readers, podcast clients and other software that supports the format.

Jump to navigation

Congratulations!

This is a valid RSS feed.

Recommendations

This feed is valid, but interoperability with the widest range of feed readers could be improved by implementing the following recommendations.

line 12, column 0: content:encoded should not contain aria-label attribute (19 occurrences) [help]
```
</description><pubDate>Mon, 12 Aug 2024 00:00:00 GMT</pubDate><content:encod ...
```
line 12, column 0: content:encoded should not contain aria-hidden attribute (19 occurrences) [help]
```
</description><pubDate>Mon, 12 Aug 2024 00:00:00 GMT</pubDate><content:encod ...
```

line 12, column 0: Non-html tag: svg (57 occurrences) [help]

</description><pubDate>Mon, 12 Aug 2024 00:00:00 GMT</pubDate><content:encod ...

line 326, column 296: Missing atom:link with rel="self" [help]

... ory>50 tips in 50 days</category></item></channel></rss>
                                             ^

Source: https://www.rainsberger.ca/blog/rss.xml

<?xml version="1.0" encoding="UTF-8"?><rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Sarah Rainsberger | Blog</title><description/><link>https://www.rainsberger.ca/</link><language>en</language><item><title>Reads - October 6, 2024</title><link>https://www.rainsberger.ca/blog/reads-2024-10-06/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/reads-2024-10-06/</guid><description>Community building advice from FeverBee, sidebar navigation advice from Tom Johnson for large documentation sites, and more!
</description><pubDate>Sun, 06 Oct 2024 00:00:00 GMT</pubDate><content:encoded>Here are some things I’ve recently been reading and enjoyed/learned from!
<ul>
<li><a href="https://www.feverbee.com/lurkersandlearners/">Why 95% Of Your Community Visitors Don’t Participate (And What You Should Do About It!)</a> and <a href="https://www.feverbee.com/engagementskills/">Stop Undervaluing Community Engagement Skills! – Communities Die Without Them</a> by Richard Mulligan of FeverBee.</li>
<li><a href="https://idratherbewriting.com/files/doc-navigation-wtd/design-principles-for-doc-navigation/">Building navigation for your documentation site: 5 best practices in design</a> by Tom Johnson at I’d Rather Be Writing.</li>
<li><a href="https://tri.be/blog/designing-navigation-for-content-heavy-sites/">Designing Navigation for Content-Heavy Sites</a> by Kyle at Modern Tribe. (He eats hot dogs.)</li>
<li><a href="https://abbycovert.com/writing/information-architecture-for-navigation/">Information Architecture for Navigation</a> by sensemaker Abby Covert.</li>
</ul>
I may come back and expand upon these, or I may follow up in later posts. There are no rules! This is my first “Reads!”</content:encoded><category>reads</category><category>community</category><category>open-source</category><category>information architecture</category></item><item><title>Tip 50 - tip your server</title><link>https://www.rainsberger.ca/blog/50-50-tip-your-server/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-50-tip-your-server/</guid><description>Use tips for actionable, optional, been-there-done-that content.
</description><pubDate>Mon, 12 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Use tips for actionable, optional, been-there-done-that content.</div></aside>
We try to <a href="https://www.rainsberger.ca/blog/50-45-and-another-thing">avoid sticky note docs</a>, where new pieces of information feel bolted on and fight for our readers’ attention. Instead, we prefer to carefully weave new content into existing documentation whenever posible.
Sometimes, information is helpful and timely, though perhaps not particularly easy to integrate. “Asides” (note, tip, caution, danger…) exist for a reason! They have their uses, but they are not interchangeable. I choose to leave “caution” and “danger” for legitimate threats that may be difficult or impossible to recover from. Just doesn’t work? That’s probably a “note.”
In the spirit of finally “tipping out” today, I’ll share when I am particularly inclined to use a “tip!” Hint, the icon we use in Astro Docs/Starlight for our tip tells you most of what you need to know…
I use tips for actions, like the rocket launching into space! A tip is something to do, not know. It may be a shortcut, or a clever alternative. It may be an extra preparation step that will make the whole (officially documented) process go smoother.
A tip is also not required. It is an “aside.” It maybe loosely or entirely tangential. Your reader can choose whether to heed it, but it’s generally understood as a Good Idea™️.
It is intented to be helpful. It is shared from the trenches of experience, a cave of wisdom, a place of love.
And that, gentle reader, is where this series takes its leave!
Thank you for joining me on this journey. I have truly appreciated the interactions to the individual posts on Mastodon. I did not know what I was signing up for, what to expect, who would care… but I certainly never felt alone.
If nothing else, I’ve enjoyed revisiting some of my past work and really forcing myself to put into words some of Past Sarah’s decisions. This has provided me some clarity, and with any luck, it’s been clear outside observers.
Tomorrow, a new journey begins! Until we meet again!
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 49 - NWTWWHB</title><link>https://www.rainsberger.ca/blog/50-49-nwtwwhb/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-49-nwtwwhb/</guid><description>What doesn&#39;t kill you makes (your docs) stronger.
</description><pubDate>Sun, 11 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>What doesn’t kill you makes (your docs) stronger.</div></aside>
“Is it good?”
“Well, it’s not worse than what we had before…”
“Ship it!”
Not every submission we receive to Astro does is… amazing. If we’re lucky, they’re helpful.
We’re not always lucky.
But, we understand that someone believed this was a valuable contribution. They willingly and voluntarily took the time to fork the repo, edit the content, create a pull request… they must really want to help!
Maintaining community-driven docs means identifying and channelling the desire to contribute. Community is the lifeblood of an open-source project. It’s who we write the docs for and the reason we exist.
We invest in our community by providing public-facing docs, and we can allow them to feel invested in us by including them in our project. Spot a typo? Fix it! Did an external link change? Update it! Want to rewrite the section on passing props to framework components? Uh… maybe let’s talk?
When I can’t immediately see how a proposed change is useful, I try to <a href="https://en.wikipedia.org/wiki/Yes,_and...">“Yes, and…”</a> I ask what they hoped to achieve. What problem were they trying to solve, and can I help explore the problem with then to see if we can find a solution that fits within Astro docs’ scope, mandate, and style?
<ul>
<li>✅ Finding a way to say yes to things!</li>
</ul>
There are myriad reasons why someone may choose to contribute. A problematic contribution is an opportunity to engage, and to figure out whether their very real issue can lead to an outcome that validates their experience and addresses their desire to be a part of the solution… without messing up your lovely docs in the process!
A standard of “not worse than what we had before” (#NWTWWHB) is inclusive. And, I am including my own half-baked ideas, too! We may not accept every submission that comes our way. But we also don’t waste as much time deciding, and our process actively discourages gate keeping or making potential contributors jump through excessive hoops.
Did you not make things worse? Congratulations! That’s all any of us can hope for at the end of the day. Welcome to Team Docs! Here’s your badge, find a spot in our FacePile…
You can have an active culture of accepting community contributions and still maintain docs quality. In fact, you have no choice! Too many people are watching now… 😅
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 48 - do it yourself</title><link>https://www.rainsberger.ca/blog/50-48-do-it-yourself/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-48-do-it-yourself/</guid><description>Use examples to enhance your point, not make it.
</description><pubDate>Sat, 10 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Use examples to enhance your point, not make it.</div></aside>
We can never have enough ideas to illustrate the sometimes abstract concepts we need to cover in our docs! Examples help contextualize ideas expressed in our terms, and relate them to our readers’ world.
As docs writers, we use both the abstract and the concrete. We can’t write for every reader, so we have to write for all readers, using every tool available to us. Examples make sense, but are they sufficient for making meaning?
One PR suggestion I often make is to describe or define the general concept before launching into examples. Your list of examples isn’t exhaustive; you won’t necessarily list what your reader is hoping to do.
Example first writing make your reader synthesize (put parts together to construct a whole) which is more challenging than analysis (breaking down a concept into its parts). You are asking your reader to create meaning out of selected examples instead of providing a solid foundation to expand upon. There is no guarantee they will draw the conclusion you want them to.
<ul>
<li>✅ Enable Astro’s view transitions to create animated transitions between different website views. This links elements from both an outgoing page and the incoming page, so you can persist or animate common elements such as a blog post image. You can even make the entire page appear to fade or slide in.</li>
<li>😐 To fade into a new page, zoom in on the image when selecting a blog post, or make the next page slide in, enable Astro’s view transitions.</li>
</ul>
Astro Docs readers are already building their own projects. I try not to make them build their own definitions, too!
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 47 - Ch-ch-ch-ch-changes</title><link>https://www.rainsberger.ca/blog/50-47-ch-ch-ch-ch-changes/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-47-ch-ch-ch-ch-changes/</guid><description>Document change like a verb, not just as a noun.
</description><pubDate>Fri, 09 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Document change like a verb, not just as a noun.</div></aside>
I get it! You’re excited to tell your community about new updates to your project. Your team worked hard and is celebrating an accomplishment. They may have done some Clever Things™️ or removed some long-standing pain points. You publish release notes or update a CHANGELOG with what you did. (mic drop; dust hands; walk away)
But, the task has only just begun for the people who use your project! Not only do they have to learn about your changes. They may have to change their own code or how they use your project.
One PR suggestion I often make is to include actionable guidance alongside the description of a change. Your project has changes. Your reader needs to make changes! Connecting those dots in your change documentation can remove a lot of the pain, suffering, and stress of upgrading to a new version.
<ul>
<li>
✅ Astro v3.0 changes the default port from 3000 to 4321. 🚀 Update any existing references to <code dir="auto">localhost:3000</code>, for example in tests or in your README, to reflect the new port <code dir="auto">localhost:4321</code>.
</li>
<li>
😐 The new default port is 4321. 🚀
</li>
</ul>
Don’t just tell them what. Show them how.
Don’t make me tap the <a href="https://vimeo.com/238673931#t=2045s">“no one ever complained that docs were too easy to read”</a> sign again!
You may think the “advice” is trivial. Surely, your reader will know what to do with the information. But, your team has already written tests for various situations and can pinpoint which areas of a project might need updating. Who wouldn’t appreciate a checklist to ensure they didn’t miss anything during a major upgrade?
It’s how we write the <a href="https://docs.astro.build/en/upgrade-astro/#upgrade-guides">Astro upgrade guide breaking changes</a> (And, I document <a href="https://contribute.docs.astro.build/upgrade-guides/breaking-changes/">our preferred breaking changes docs format</a> in Astro Docs Docs.)
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 46 - it's not a bug; it's a feature!</title><link>https://www.rainsberger.ca/blog/50-46-not-a-bug-its-a-feature/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-46-not-a-bug-its-a-feature/</guid><description>Emphasize the positive! Help your readers achieve, not avoid.
</description><pubDate>Thu, 08 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Emphasize the positive! Help your readers achieve, not avoid.</div></aside>
Docs is a resource for how things work… and is often consulted when they don’t! Troubleshooting references can help people look up their issue by problem or symptom. However, when people are in your docs to learn or explore, there is nothing wrong with presenting an idealized state of your project.
Are there caveats and gotchas in your project? I’d be shocked if there weren’t! Will everyone hit them? Maybe not. Should docs scare someone preemptively? I prefer not to.
One PR suggestion, contributed by an Astro Team Docs member, is to help your reader do X to achieve Y, rather than to avoid Z. Turn that frown upside down! That thing that you’re worried might not work if they get it wrong? It’s a feature of your project when they get it right! Help them succeed.
<ul>
<li>
✅ To run middleware for pre-rendered pages, set <code dir="auto">edgeMiddleware: true</code>. This allows you to use middleware to perform actions such as authentication checks or redirects while still rendering static HTML output.
</li>
<li>
😐 If you use Middleware to implement authentication, redirects, or similar things, you may need to enable <code dir="auto">edgeMiddleware: true</code>. Otherwise, your Middleware will not run at runtime for pre-rendered pages.
</li>
</ul>
“Avoid” threatenening your reader with consequences. Don’t make them juggle learning how something works in theory with how it might go wrong in practice. Problems are only relevant to people who have them. To everyone else, it’s more information being thrown at them, sometimes making them feel like they have to be overly cautious.
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 45 - and another thing...</title><link>https://www.rainsberger.ca/blog/50-45-and-another-thing/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-45-and-another-thing/</guid><description>Every new fact is &#39;another thing&#39;, but you don&#39;t always need to call attention to it!
</description><pubDate>Wed, 07 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Every new fact is “another thing,” but you don’t always need to call attention to it!</div></aside>
In Astro docs, we try to limit the number of “asides” (UI elements marked as “note”, “tip”, “caution” etc… like the one above!) to information that is truly tangential to the core material in some way. Otherwise, if it’s just part of “how things work,” we believe we should include it in the regular documentation text.
We have to have this guidance because it is very common for people to learn a new fact, realize it’s not explicity stated in our docs, and then submit a contribution to add a “tip” or a “note” with this new piece of information.
Unfortunately, this TIL (“Today I learned…”) approach can easily lead to docs looking like a board of sticky notes. When everything stands out, nothing stands out. <a href="https://en.wikipedia.org/wiki/Banner_blindness">Banner blindness</a> is real!
In addition to, “omg stop making everything a flaming orange caution; your project won’t explode because you didn’t add a client directive”, one PR suggestion I’ll make is to remove extra words like “also” when you don’t mean to emphasize the “additional-ness” of an idea. “Also” is helpful to call out a “similar addition,” but not every addition.
“Components are reusable. Components are also composable. You can also write components from several different frameworks. Components can also pass and recieve props.” It’s easy to go overboard “sticky note”-ing “also” on to every new idea, whether or not the similarity of the addition is interesting, important, true, or helpful.
<ul>
<li>✅ To avoid repeating the same HTML elements on every page, you can move common elements into a layout component. You can use as many or as few layout components as you’d like.</li>
<li>😐 To avoid repeating the same HTML elements on every page, you can move common elements into a layout component. You can also use as many or as few layout components as you’d like.</li>
</ul>
Just like <a href="https://www.rainsberger.ca/blog/50-38-this-and-that">“but” sets the reader up to expect a surprise</a>, “also” can make the reader think they missed something important that came before. We can file this under “words mean things,” and I like to make sure that each word I include in my docs is contributing to the reader’s experience as intended.
Certainly, if what came before is helpful to understanding this sentence, I will make that connection! If a superflous word like “also” gives me a better reading flow, I might decide to use it. It’s (usually!) not wrong. It’s occasionally overwhelming. It’s sure to grab my attention while editing just in case it doesn’t provide any benefit.
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 44 - we did it!</title><link>https://www.rainsberger.ca/blog/50-44-we-did-it/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-44-we-did-it/</guid><description>Separate yourself from, and instead focus on, your reader.
</description><pubDate>Tue, 06 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Separate yourself from, and instead focus on, your reader.</div></aside>
I don’t know your docs situation. I don’t know your style guide. I don’t know your constraints, your stakeholders, your audience. I also don’t know your stress level, your mood, or your past experiences. You do.
Some consider it “friendly” to write instructions as if you were sitting right there beside your reader, going through the steps with them. But, you’re not. You’re separated by time and space, at a minimum. There’s probably a lot more going on that you don’t share.
“We” is — at best — a lie. At its worst, it’s condescending. It does not reliably make it through the “avoid sarcastic reader reactions” editing pass. (Now, we see… “Who sees? I sure as heck don’t see this!”)
It can also be unclear who “we” is referring to in your docs. In some situations, it is used to include the reader. Other times, it may be used to speak on behalf of the project, as in “We recommend…”
One PR suggestion I’m often making is to address, not include, the reader. This most often takes the form of changing step-by-step instructions from “We will now create a new page…” to “You will now create a new page…”
And, I hope if you do that, it feels a little weird to you, and it prompts you to try alternatives such as, “You must now create a new page…” Eventually, I hope it feels the most natural to just write “Create a new page…” and <a href="https://www.rainsberger.ca/blog/50-41-if-you-please">give your reader a direct instruction</a>!
<ul>
<li>✅ Use the <code dir="auto">useStoryblokApi</code> hook to query your data. This will initialize a new client instance using your integration configuration.</li>
<li>😐 We will use the <code dir="auto">useStoryblokApi</code> hook to query our data. This will initialize a new client instance using our integration configuration.</li>
</ul>
Trying to “support” your reader through your steps with “we” can quickly take a turn from friendly to awkward, or even disturbing. “We will use the API to…” is one thing. But referring to “our” data feels a little intrusive.
Removing the reader-inclusive “we” also has an added benefit: it prevents you from thinking about yourself in the instruction. Using (or implying) “you” naturally puts the emphasis on your reader, and what they are doing. It guides you towards thinking about helping them. What might their set up look like? Writing “our” can trick you into thinking about your own context or situation that your reader might not share.
I know I won’t change every mind with this tip, even though it’s one of my favourites! Using “we” is such a common docs practice that I can only assume that some find value in it.
Whatever your take on “we”, can we at least agree that using “I” is off the table? I don’t know about you, but I don’t expect to be reading a personal story or take in official docs.
<ul>
<li>😬 I will use the <code dir="auto">useStoryblokApi</code> hook to query my data. This will initialize a new client instance using my integration configuration.</li>
</ul>
(I mean, it’s not just me, right? You could imagine a reading where that even comes across as creepy…)
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 43 - what's in a name?</title><link>https://www.rainsberger.ca/blog/50-43-whats-in-a-name/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-43-whats-in-a-name/</guid><description>Sneak in &quot;extra docs&quot; with meaningful example file names.
</description><pubDate>Mon, 05 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Sneak in “extra docs” with meaningful example file names.</div></aside>
Naming is hard when creating features and designing APIs. But naming in docs examples can be fun and educational!
Code examples are… just that: examples. They are illustrative of larger concepts, not a function or configuration value you’ll be stuck with.
And, you’re limited in how many you can show. You can’t create examples for every situation your user might encounter while using your project. So, these examples need to help your reader make connections and form patterns to apply to their situation.
One PR suggestion I often make is to choose example file names that reinforce their use. It is helpful for readers to see the typical files and folder structure of your own project reflected in examples. This allows them to relate your examples to their own code.
You can squeeze even more meaning out of an example file name with a little creativity:
<ul>
<li>✅ <code dir="auto">excludedFiles: ['node_modules/chonky-module/not-this-huge-file.mp4']</code></li>
<li>😐 <code dir="auto">excludedFiles: ['files/subdirectory/foo.txt']</code></li>
</ul>
(Is “chonky” in your style guide? 😅)
This is also a safer way to inject a tiny bit of humour into your docs without “telling a joke.” Even if my reader doesn’t get the reference “chonky” (or why it’s hilarious, thank you very much), “huge” is descriptive without trying so hard.
This example still conveys a little extra meaning even if “huge” isn’t a familiar word. Media is a reasonable example of a potentially large file. Excluding items from the <code dir="auto">node_modules</code> folder is also a common task my reader might perform.
Whether you go with the familiar and expected, or the unusual and whimsical, you can get “bonus docs” when you pay special attention to your example file names!
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 42 - knock knock, who's there?</title><link>https://www.rainsberger.ca/blog/50-42-whos-there/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-42-whos-there/</guid><description>Assume that your reader knows whose docs they&#39;re reading.
</description><pubDate>Sun, 04 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Assume that your reader knows whose docs they’re reading.</div></aside>
Writers work to avoid redundant phrases in their writing like, “very unique” or “new innovation.” These modifiers repeat the idea already contained in the word being modified. In documentation, where we value writing concisely, these phrases are “quick wins” for getting that word count down (and, keeping that reader energy up)!
There are other, sneakier ways that redundancy can creep into our writing.
One PR suggestion I will make is to use the name of the project only when it’s helpful for clarity. If my sentence works without name-checking the project, I can delete it!
<ul>
<li>✅ You can add MDX pages to your project by adding <code dir="auto">.mdx</code> files in the special <code dir="auto">src/pages/</code> folder.</li>
<li>😐 In Astro, you can add MDX pages to your project by adding <code dir="auto">.mdx</code> files in the special <code dir="auto">src/pages/</code> folder.</li>
</ul>
This format is useful when comparing to a similar project, especially one that may work differently. If you’re describing multiple projects, then identifying the project is important enough to be the stage setter of the sentence. Similarly, in a “What the heck is Astro?” section, your reader might be so unfamiliar with your project, what it does, and how it works that it’s like you’re comparing it… to anything they might know so you can make a meaningful connection!
For the rest (most?) of our docs that explain “how a thing works in Astro,” emphasizing the in Astro part isn’t necessary and can be annoying for the reader. You can perform a, “What other project would we be talking about?” check to decide. (Add it to your “avoid sarcastic reader reactions” editing pass.)
An unhelpful “in Astro” sometimes even feels to me a little like talking about yourself in the 3rd person. It also implies a comparison that no one made, and can feel “invented” just so you can take an agressive marketing position. (“Oh, did you realize that in ASTRO you can just…”) And, if you think I’m “inventing interpretations” of a tiny, two-word phrase, may I introduce you to social media? 😅
Mention your project when it’s helpful. Otherwise, trust that your reader knows where they are!
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 41 - if you please</title><link>https://www.rainsberger.ca/blog/50-41-if-you-please/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-41-if-you-please/</guid><description>Docs is not a conversation. Skip the pleasantries!
</description><pubDate>Sat, 03 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Docs is not a conversation. Skip the pleasantries!</div></aside>
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.”
<ul>
<li>✅ Adding the official Astro MDX integration allows you to write standard Markdown with JSX variables, expressions and components.</li>
<li>😐 Please install the official <code dir="auto">@astrojs/mdx</code> integration to use JSX variables, expressions and components.</li>
</ul>
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!
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 40 - make my day</title><link>https://www.rainsberger.ca/blog/50-40-make-my-day/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-40-make-my-day/</guid><description>&quot;Make things happen&quot; in your life, not in your docs writing.
</description><pubDate>Fri, 02 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>“Make things happen” in your life, not in your docs writing.</div></aside>
Much of our docs writing involves cause and effect. If you perform this action or set this value, then this will happen. When you start the dev server, you will see a live preview of your site.
Sometimes, the underlying mechanisms aren’t particularly important or interesting to our readers. But sometimes, it is helpful for our readers to know more than, “This makes that happen.” (handwavy gesture)
Just as it’s helpful to <a href="https://www.rainsberger.ca/blog/50-26-use-this">use the words you mean</a>, adding precision to connected events gives your reader extra context and sometimes provides even more guidance than you originally intented… potentially saving you some writing (and your reader, some reading)!
One PR suggestion I’ll make is to provide more detail about a chain of events when it helps the reader use my project. If I can provide some extra context, maybe tap into some prior knowledge, I can make an explanation more “sticky.” Perhaps knowing a bit more about what happened can help them predict what’s coming next, even before they read it. Or, I might use this as a pedagogical opportunity to reinforce the vocabulary my readers need to be successful with my project.
However, too many details can be overwhelming. And, most readers aren’t interested in learning about the inner workings of your project out of curiosity or for its own sake. If my reader can’t do anything with the extra information — if knowing this wouldn’t change their behaviour — I tend to leave it out.
<ul>
<li>✅ When you import Markdown and MDX files in an Astro component, you receive an object containing their exported properties.</li>
<li>😐 Importing Markdown and MDX files makes their exported properties available.</li>
</ul>
You can decide for yourself when to simply “make this rabbit disappear” and when to let your audience in on the trick. Can you provide more detail that helps your reader be a more confident, competent user of your project if you go into more details?
These kinds of edits also lend themselves to writing sentences from the reader’s perspective. This particular example changes the subject of the sentence from “the files” to the reader, which is an added benefit if that’s the style you’re going for. Many docs today adopt a strong “you” vibe, and this example would fit right in with that friendly, casual style!
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 39 - smarty pants</title><link>https://www.rainsberger.ca/blog/50-39-smarty-pants/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-39-smarty-pants/</guid><description>Don&#39;t sound smart; make your reader feel smart!
</description><pubDate>Thu, 01 Aug 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Don’t sound smart; make your reader feel smart!</div></aside>
Why do so many contributions to documentation sound like someone trying to “be smart?” I think people naturally tend to use “elevated” language because they think of docs as “very serious reference material.”
Docs isn’t Shakespeare… or is it? Shakespeare’s writing only sounds “fancy” to us now because the language of their time is so different from the language of our time. Shakespeare’s plays were not written to challenge the audience. They were entertainment, and not always of the highest form.
We may work with complex or abstract subject matter, but our docs writing is meant to be understood. There is no point in having docs that aren’t consumable by our readers.
One PR suggestion I’ll often make is to simplify word choices and phrases so that the meaningful words stand out. Don’t waste your reader’s energy on “harder” forms of words that distract from the project or industry terms that we can’t simplify without losing meaning. Some of your sentences will be challenging enough for some of your readers even when they are as clear and concise as possible!
<ul>
<li>✅ You can access the Cloudflare bindings and environment variables through the Adapter API.</li>
<li>😐 You have the posibility to gain access to all the Cloudflare bindings and utilize any previously configured environment variables through the Adapter API.</li>
</ul>
These sentences may feel awkward to write. (“This is “official documentation” — am I being “proper” enough?” “If I write too simply, will my audience feel talked down to?”) But, for the ones who need it, this may be the difference between them being able to use your project and being forced to give up.
And the ones who don’t… most of the time, they won’t even notice. They’ll have a great “no fluff, just stuff” experience.
<a href="https://vimeo.com/238673931#t=2045s">No one ever complained because docs were too easy to read</a>.
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 38 - this and that</title><link>https://www.rainsberger.ca/blog/50-38-this-and-that/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-38-this-and-that/</guid><description>Save &quot;but&quot; for a truly unexpected turn of events. You can use &quot;and&quot; more than you think!
</description><pubDate>Wed, 31 Jul 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Save “but” for a truly unexpected turn of events. You can use “and” more than you think!</div></aside>
Docs is fact, not fiction. There’s no story arc, no conflict, no twists and turns. You’re not trying to surprise your reader… unless you count surprising them with how great your docs are! 🙌
Readable docs follow a straight, predictable, boring path. I’m usually trying to remove complications and contradictions, not highlight them.
One PR suggestion I will make is to try replacing “but” with “and” to see whether you can join ideas in a more neutral way. If it fits, it sits! “But” conveys to your reader that the relationship between two ideas is somehow unexpected, surprising or contradicting. And usually, our stories just aren’t that interesting. Furthermore, now they have to process the two pieces of information you wanted them to know and a (perhaps errant?) third concept: why these two ideas are in conflict with each other.
<ul>
<li>✅ Your original image will be copied unprocessed to the build folder, and Astro’s image integration will also return optimized versions of the image.</li>
<li>😐 Your original image will be copied unprocessed to the build folder, but Astro’s image integration will also return optimized versions of the image.</li>
</ul>
If they both work equally well, the tie goes to “and” because it evokes… absolutely nothing at all! “But” holds the promise of something different, interesting, challenging. “But” brings the popcorn. “And” hands you a glass of tepid tap water.
Of course, don’t be afraid to use “but” when there really is something contradictory or unexpected between two ideas you’re joining together. Sometimes it’s the right word for the job in that sentence! But, I also want to make sure that I’m not the one overcomplicating things by putting those ideas together in the first place! 😅
I find that too many “but”s in my writing could be a sign that I’m bouncing back and forth between disjointed thoughts. Maybe I can find a better way to combine them so they flow from one to the next without taking that hard turn.
You can take advantage of your “captive docs audience” — you don’t have to keep them on the edge of their seat. They won’t lose interest and leave if you’re not complelling enough. They want “just the facts” and “none of the drama.” Can I refill your glass?
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 37 - right words, wrong place</title><link>https://www.rainsberger.ca/blog/50-37-right-words-wrong-place/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-37-right-words-wrong-place/</guid><description>You may need to &#39;rearrange&#39; to support your reader&#39;s journey, not rewrite.
</description><pubDate>Tue, 30 Jul 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>You may need to “rearrange” to support your reader’s journey, not rewrite.</div></aside>
Lots of docs writing tips focus on specific word usage: use them correctly; use more precise words; use fewer of them! Sometimes, our words are already pretty good.
We can’t get complacent, though! Sometimes writing that would fit very well in one place of your documentation doesn’t quite work in another.
One PR suggestion I often make doesn’t significantly change words, but rearranges them to align with the purpose of the content. Writing may be clear, correct, and even helpful, but presented at the wrong time. The example below is going to need some context to show why I prefer one over the other. Otherwise, it’s difficult to tell!
The examples below occur immediately after a heading called “Setup” and the reader is assumed to be staring at a new, blank project.
<ul>
<li>
✅ Astro starter projects include a <code dir="auto">tsconfig.json</code> file in your project. This file is important so that tools like Astro and VS Code know how to understand your project. Some features (like npm package imports) aren’t fully supported in the editor without a <code dir="auto">tsconfig.json</code> file. If you install Astro manually, be sure to create this file yourself.
</li>
<li>
😐 Astro always treats your component code as TypeScript, but some features (like npm package imports) aren’t fully supported in the editor without a <code dir="auto">tsconfig.json</code> file. Even if you don’t write TypeScript, this file is important so that tools like Astro and VS Code know how to understand your project. Astro starter projects include this file, but if you install Astro manually, be sure to create it yourself.
</li>
</ul>
The difference is subtle, but I think it exists. In this situation, I prefer to first call attention to the file itself. In fact, I do like the nuance that “Astro treats your code as TypeScript” (even if you only write JavaScript). In another context, it’s a great lead-in! I would totally use it to set a stage, just not this stage.
We wouldn’t list steps out of order. (Well, we wouldn’t do that. 😅) A sequence of concrete steps, like a set of instructions, gives us a natural structure to follow in our writing. Absent that, we have to do the heavy lifting ourselves to structure our (good) content in the context of the reader’s journey through our docs, and the purpose of each page.
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 36 - not my problem</title><link>https://www.rainsberger.ca/blog/50-36-not-my-problem/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-36-not-my-problem/</guid><description>Don&#39;t take responsibility for documenting someone else&#39;s project.
</description><pubDate>Mon, 29 Jul 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Don’t take responsibility for documenting someone else’s project.</div></aside>
No docs site is an island! Astro docs overlaps with concepts from HTML, CSS, and JavaScript. Additionally, Astro can be connected to a CMS or backend service and deployed on a hosting platform. That’s potentially a lot of documentation our community needs that is outside of our own project!
Including other projects or services in your own documentation may be unavoidable. Who is responsible for publishing and maintaining “definitive guide to deploying Astro on Netlify” for example: Astro, or Netlify? (I know what my answer is…) In practice, the line may not always be easy to draw.
One PR suggestion I often make is to keep the focus on “working with” services and possible interactions between projects, not (re)documenting how they work. And absolutely avoid describing their UI at all costs! It is still possible to provide helpful guidance without providing too many details that are subject to change. Use language consistent with the other project’s documentation so your readers can cross-check or search in their documentation when they need further instruction.
<ul>
<li>
✅ In your CMS dashboard, create a new post named <code dir="auto">test-post</code> with the content type <code dir="auto">blogPost</code>.
</li>
<li>
😐 Sign in to your CMS and click on your user profile to access your dashboard. Click the green <code dir="auto">+</code> button the upper right corner to create a new post. Scroll down to the field for entering the content type and select <code dir="auto">blogPost</code> from the drop-down menu.
</li>
</ul>
When Astro’s code changes, I know about it. I monitor the appropriate repositories. I am directly notified to review accompanying docs changes, and I am even brought in to assist <a href="https://www.rainsberger.ca/blog/50-19-be-the-change">writing helpful CHANGELOG entries</a>. When a feature, process, setting, or website UI changes at Netlify… I wouldn’t even know until my docs are already wrong and I am be at the mercy of a reader discoving and pointing it out.
“Docs are never done” and require continual (continuous? 😅) maintenance. Docs will occassionally be out of date. It may not always be my responsibility, but it’s my problem! To help keep up, I don’t take on any more responsibility than I need to.
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 35 - link in bio</title><link>https://www.rainsberger.ca/blog/50-35-link-in-bio/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-35-link-in-bio/</guid><description>Links are going to be clicked! Use them strategically when you want readers to leave your page.
</description><pubDate>Sun, 28 Jul 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Links are going to be clicked! Use them strategically when you want readers to leave your page.</div></aside>
Inline text links are an efficient way to provide readers with optional extra context at the moment they encounter potentially unfamilar content. Many documentation sites link liberally to help readers discover and navigate to related content.
Links to source material also allow us to write content once (or, in the case of external links, not at all!) to reduce our maintenance burden and provide a single source of truth. Links directly within our text signals to our readers that there’s more about this elsewhere if they need it, without cluttering the page with “Read more about…” throughout.
However, links are distracting:
<blockquote cite="https://www.roughtype.com/?p=1378">Where a footnote gives your brain a gentle nudge, the link gives it a yank. What’s good about a link – its propulsive force – is also what’s bad about it.</blockquote>
— Nicholas Carr, <cite><a href="https://www.roughtype.com/?p=1378">Experiments in delinkification</a></cite>
One PR suggestion I’m often making is to remove linked text when I feel it’s more helpful to keep the reader following the current page’s flow. Like many edits, this is a judgement call. However, there are some standard situations where it’s helpful to support reading without interruption: following instructions, being introduced to an entirely new concept, or anything else where the reader might need to focus or may already be holding multiple concepts in their head.
<ul>
<li>
✅ How do islands work? By default, Astro will render every UI framework component to just HTML &#x26; CSS, stripping out all client-side JavaScript automatically.
</li>
<li>
😐 How do islands work? By default, Astro will render every <a href="https://docs.astro.build/en/guides/framework-components/">UI framework component</a> to just <a href="https://en.wikipedia.org/wiki/HTML">HTML</a> &#x26; <a href="https://en.wikipedia.org/wiki/CSS">CSS</a>, stripping out all client-side <a href="https://en.wikipedia.org/wiki/JavaScript">JavaScript</a> automatically.
</li>
</ul>
We paid particular attention to our linking when writing <a href="https://docs.astro.build/en/tutorial/0-introduction/">the Astro introductory tutorial</a>. This tutorial was designed to be accessible to learners who may never have used common web development tools such as VS Code and GitHub, and who have never deployed a website. Reducing distractions and helping them progress through the instructions is incredibly important in this kind of situation!
Don’t make your readers fight the temptation of the <a href="https://www.rainsberger.ca/blog/50-29-seen-and-not-heard">visual decoration that links provide</a> which contains the promise of something more! (What is at that link??)
Readers also don’t know whether you intend for them to click a text line right now! (You put it there, after all.) It can be interpreted as an indication that you don’t think they’ll understand what comes next. And if they find inline links on that page, who knows when they’ll get back to the content they originally came to read?
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 34 - show what to do</title><link>https://www.rainsberger.ca/blog/50-34-show-what-to-do/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-34-show-what-to-do/</guid><description>Show the right thing so readers don&#39;t internalize the wrong thing.
</description><pubDate>Sat, 27 Jul 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Show the right thing so readers don’t internalize the wrong thing.</div></aside>
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.”
<ul>
<li>
✅ <code dir="auto">&#x3C;script>...&#x3C;/script></code>
</li>
<li>
😐 ❌ This doesn’t work! ❌ <code dir="auto">&#x3C;button onClick={handleClick}>Nothing will happen when you click me!&#x3C;/button></code>
</li>
</ul>
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.
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 33 - what's your problem?</title><link>https://www.rainsberger.ca/blog/50-33-whats-your-problem/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-33-whats-your-problem/</guid><description>Start troubleshooting advice with the observable error, not what led to it.
</description><pubDate>Fri, 26 Jul 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>Start troubleshooting advice with the observable error, not what led to it.</div></aside>
Much of our documentation covers what happens when things work properly. Sometimes, our writing is for when things go wrong.
And when things go wrong, the first thing our readers experience is that something is not functioning as expected. They may have already realized what caused the error (step 2) when they consult our docs. But it’s likely they have not yet progressed to step three: knowing what to do about it. That’s what we’re for!
One PR suggestion I will make is to follow the reader’s journey through an issue they way they experienced it. The cause of the error may be unknown to them, but they can identify the problem they are having.
<ul>
<li>
✅ If the Translation Status Overview incorrectly shows “needs updating” for a page (e.g. a typo fix to an English page was merged without the “ignore” label and triggered the status update), take the following steps to manually update the tracker:
</li>
<li>
😐 If a PR that should have been marked as an ignored change was merged without the label, the Translation Status Overview will consider the page’s translations as “needs updating” when there are no changes to translate. If this occurs, and there aren’t any other updates needed for that translation, take the following steps to manually update the tracker:
</li>
</ul>
Starting from the reason to explain what goes wrong feels to me like, “Fun fact: if you do this, this will happen!” I’m not entirely convinced that fact is so fun to someone who’s experiencing it.
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item><item><title>Tip 32 - defining the obvious</title><link>https://www.rainsberger.ca/blog/50-32-defining-the-obvious/</link><guid isPermaLink="true">https://www.rainsberger.ca/blog/50-32-defining-the-obvious/</guid><description>The better the name, the harder you have to work for the definition.
</description><pubDate>Thu, 25 Jul 2024 00:00:00 GMT</pubDate><content:encoded><aside aria-label="Tip"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.43909 8.85483L1.44039 8.85354L4.96668 5.33815C5.30653 4.99386 5.7685 4.79662 6.2524 4.78972L6.26553 4.78963L12.9014 4.78962L13.8479 3.84308C16.9187 0.772319 20.0546 0.770617 21.4678 0.975145C21.8617 1.02914 22.2271 1.21053 22.5083 1.4917C22.7894 1.77284 22.9708 2.13821 23.0248 2.53199C23.2294 3.94517 23.2278 7.08119 20.1569 10.1521L19.2107 11.0983V17.7338L19.2106 17.7469C19.2037 18.2308 19.0067 18.6933 18.6624 19.0331L15.1456 22.5608C14.9095 22.7966 14.6137 22.964 14.29 23.0449C13.9663 23.1259 13.6267 23.1174 13.3074 23.0204C12.9881 22.9235 12.7011 22.7417 12.4771 22.4944C12.2533 22.2473 12.1006 21.9441 12.0355 21.6171L11.1783 17.3417L6.65869 12.822L4.34847 12.3589L2.38351 11.965C2.05664 11.8998 1.75272 11.747 1.50564 11.5232C1.25835 11.2992 1.07653 11.0122 0.979561 10.6929C0.882595 10.3736 0.874125 10.034 0.955057 9.7103C1.03599 9.38659 1.20328 9.09092 1.43909 8.85483ZM6.8186 10.8724L2.94619 10.096L6.32006 6.73268H10.9583L6.8186 10.8724ZM15.2219 5.21703C17.681 2.75787 20.0783 2.75376 21.1124 2.8876C21.2462 3.92172 21.2421 6.31895 18.783 8.77812L12.0728 15.4883L8.51172 11.9272L15.2219 5.21703ZM13.9042 21.0538L13.1279 17.1811L17.2676 13.0414V17.68L13.9042 21.0538Z"></path><path d="M9.31827 18.3446C9.45046 17.8529 9.17864 17.3369 8.68945 17.1724C8.56178 17.1294 8.43145 17.1145 8.30512 17.1243C8.10513 17.1398 7.91519 17.2172 7.76181 17.3434C7.62613 17.455 7.51905 17.6048 7.45893 17.7835C6.97634 19.2186 5.77062 19.9878 4.52406 20.4029C4.08525 20.549 3.6605 20.644 3.29471 20.7053C3.35607 20.3395 3.45098 19.9148 3.59711 19.476C4.01221 18.2294 4.78141 17.0237 6.21648 16.5411C6.39528 16.481 6.54504 16.3739 6.65665 16.2382C6.85126 16.0016 6.92988 15.678 6.84417 15.3647C6.83922 15.3466 6.83373 15.3286 6.82767 15.3106C6.74106 15.053 6.55701 14.8557 6.33037 14.7459C6.10949 14.6389 5.84816 14.615 5.59715 14.6994C5.47743 14.7397 5.36103 14.7831 5.24786 14.8294C3.22626 15.6569 2.2347 17.4173 1.75357 18.8621C1.49662 19.6337 1.36993 20.3554 1.30679 20.8818C1.27505 21.1464 1.25893 21.3654 1.25072 21.5213C1.24662 21.5993 1.24448 21.6618 1.24337 21.7066L1.243 21.7226L1.24235 21.7605L1.2422 21.7771L1.24217 21.7827L1.24217 21.7856C1.24217 22.3221 1.67703 22.7579 2.2137 22.7579L2.2155 22.7579L2.22337 22.7578L2.23956 22.7577C2.25293 22.7575 2.27096 22.7572 2.29338 22.7567C2.33821 22.7555 2.40073 22.7534 2.47876 22.7493C2.63466 22.7411 2.85361 22.725 3.11822 22.6932C3.64462 22.6301 4.36636 22.5034 5.13797 22.2464C6.58274 21.7653 8.3431 20.7738 9.17063 18.7522C9.21696 18.639 9.26037 18.5226 9.30064 18.4029C9.30716 18.3835 9.31304 18.364 9.31827 18.3446Z"></path></svg>Tip<div>The better the name, the harder you have to work for the definition.</div></aside>
Some things seem like they should be so easy to define: <code dir="auto">redirect()</code>… redirects! 😅
It’s great when your devs take care to choose intuitive names. This does some of your documentation’s heavy lifting, maybe even helping people avoid coming to docs at all. However, when they do come to docs, it’s because that “obvious” name wasn’t enough.
One PR suggestion I’m often making is to not rely on the common meaning of a word to explain what it means. Your docs need to serve readers of all experience levels, and language levels. Some words have slightly (or significantly) different meanings in particular fields. Some of the terms we document are general software concepts that our reader may or may not happen to know. Our project’s “take on” or “implementation of” these established concepts may or may not differ from the standard.
<ul>
<li>
✅ <code dir="auto">Astro.rewrite()</code> allows you to serve content from a different URL or path without redirecting the browser to a new page.
</li>
<li>
😐 <code dir="auto">Astro.rewrite()</code> allows you to rewrite a request at runtime.
</li>
</ul>
Another alternative is to link externally when you are referring to a standard concept such as a Response object or HTML element. In these situations, I will consider the reader experience of being sent out (the flow) of our own docs. Sometimes canonical sources, while accurate, may not be “quick glance” resources. I prefer not to send my reader into another reading task, when they’re already trying to get through my docs!
<div> <a href="https://www.rainsberger.ca/blog/50-docs-tips-in-50-days"> See the whole list of tips! </a> </div> </content:encoded><category>docs tips</category><category>50 tips in 50 days</category></item></channel></rss>

If you would like to create a banner that links to this page (i.e. this validation result), do the following:

Download the "valid RSS" banner.
Upload the image to your own server. (This step is important. Please do not link directly to the image on this server.)
Add this HTML to your page (change the image src attribute if necessary):

<a href="http://www.rssboard.org/rss-validator/check.cgi?url=https%3A//www.rainsberger.ca/blog/rss.xml"><img src="valid-rss-rogers.png" alt="[Valid RSS]" title="Validate my RSS feed" /></a>

If you would like to create a text link instead, here is the URL you can use:

http://www.rssboard.org/rss-validator/check.cgi?url=https%3A//www.rainsberger.ca/blog/rss.xml

Home · About · News · Docs · Terms

Software created by Sam Ruby, Mark Pilgrim, Joseph Walton and Phil Ringnalda

RSS Advisory Board

Really Simple Syndication specifications, tutorials and discussion

RSS Validator

Congratulations!

Recommendations

Source: https://www.rainsberger.ca/blog/rss.xml