Tip 32 - defining the obvious

Jul 25, 2024

Some things seem like they should be so easy to define: redirect()… 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.

✅ Astro.rewrite() allows you to serve content from a different URL or path without redirecting the browser to a new page.
😐 Astro.rewrite() allows you to rewrite a request at runtime.

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!

See the whole list of tips!

Toggle Comments