Tip 48 - do it yourself

Aug 10, 2024

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.

✅ 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.
😐 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.

Astro Docs readers are already building their own projects. I try not to make them build their own definitions, too!

See the whole list of tips!

Toggle Comments