Tip 40 - make my day

Aug 2, 2024

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 use the words you mean, 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.

✅ When you import Markdown and MDX files in an Astro component, you receive an object containing their exported properties.
😐 Importing Markdown and MDX files makes their exported properties available.

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!

See the whole list of tips!

Toggle Comments