Tip 11 - don't regret what could have been

Jul 4, 2024

Writing step-by-step guides for using Astro features is challenging in part because there are often lots of ways to do the same thing! When your readers have choices, you can’t be sure which ones they will make. And, you don’t know which decisions they have already made to create the current state of their project.

One PR edit I regularly make is to remove references to previous paths not taken and instead create alternative instructions. Your reader is following your instructions to complete a task. They want to get out of docs as soon as possible and back to their project. Don’t make them go back and replay steps, even just mentally, in an alternate universe.

✅ `## Alternative: using collocated images”
😐 “You could have put your images with your Markdown files in the same folder…”

Imagine getting part way through a set of instructions, pleased that everything is going well, only to find out that three steps ago, you could have done something different. Well, I was feeling pretty good about my progress. Now apparently there’s a choice I could have made earlier. (Should have made earlier? Would that have been better? How do I decide? Why are you telling me NOW?) What kind of life is Alternate Universe Me living? Do I go back and take the other path?

If you do want to include alternatives, plan and separate your reader journeys. You can try to funnel your readers into the appropriate version upfront. Or, you can have one basic recipe, then create sections for variations or “substitutions.” It’s OK to be opinionated and provide one happy path. Your advanced or adventurous users will experiment and adapt to their own projects, if they even tried to stick to the guide faithfully at all. (“I made this recipe, but instead of cream I used coconut oil, and instead of flour I used flax seed…“)

Ideally, we want to support every reader! We want to show you how to do it this way, or that way, or even an entirely different way. But, we also want to make sure that you have a clear path for the one way you do end up using, undistracted by thoughts of what might have been.

And, this also gives you an excuse to make more headings and improve page navigation!

See the whole list of tips!

Toggle Comments