Skip to content

Tip 28 - this time

Because docs has to be written for everyone, we often canā€™t know our readersā€™ prior actions and experiences. But, with guided walkthroughs, itā€™s safe to assume theyā€™ve followed any and all previous steps. In my books, thatā€™s fair game for an assumed frame of reference!

One PR suggestion I often make is to point out when a similar or identical step has already been performed. This can assure your reader that yes, theyā€™ve seen this before. It can also helpfully call attention to subtle differences.

Use the same method to fetch data your data from Contentful as above, but this time, on a page that will create a unique page route for each blog post.

Create a new file named [slug].astro in src/pages/posts/.

As you previously did in src/pages/index.astro, import the BlogPost interface and contentfulClient from src/lib/contentful.ts.

This time, fetch your data inside a getStaticPaths() function.

Most of the time, I donā€™t want to presume that my reader has read anything else earlier on the pageā€¦ and certainly not on any other page! One disadvantage of using precise headings as anchor links is sending your reader to a part of the page where even the preceeding line (and often helpful context!) is scrolled out of view.

However, your reader is working through a set of instructions from top to bottom. It is helpful to point out when they should find a task familiar (ā€œAre we just going to pretend that we havenā€™t done this before?ā€) as well as when (and how) they should not mindlessly repeat it.

Toggle Comments

Ā© 2021 - 2024 Sarah Rainsberger. Except where otherwise noted, and/or quoting external sources, the content of this site is licensed under CC BY-NC-SA 4.0