Tip 31 - as not shown here
You will rarely hear me complaining about a good âThe following example showsâŠâ preamble to a code snippet! Introducing code blocks is standard Astro docs practice.
Prefacing these examples with a hand-wavy âlike thisâ makes your reader guess which part of the code sample youâre talking about. Itâs a hard habit to break and I totally understand the impulse. This means I get lots of practice helping writers get specific to direct readers to their desired take aways. While not as common, I would like to further suggest that we can remove ânot like thisâ from our writing patterns.
One PR suggestion I occassionally have to make is to constrain your introduction to what the example actually shows. There is a time and a place for comparison and contrast. But your readers simply canât focus their attention on too many things at once, and especially when one of those things isnât even there.
-
â The following examples shows CSS written in a
<style>
tag for styles scoped to the individual component. -
đ While in this example the component is styled using a scoped
<style>
tag, pages can also be styled using global CSS.
Presenting concepts that are not demonstrated in the example is information overload. How something works and how something works differently from something else are different concepts. It also requires already understanding the second thing, or else the comparison isnât helpful.
An introduction like above can also âintroduceâ more questions than it answers. (âWhy are you telling me about pages and global styling, while showing me scoped component styling? Is this more common or preferred? How do I style a page globally? Why arenât you showing me that? Should I be doing that instead? Why would you bring it up?â)
It can be challenging enough to make sure our readers are making the connections we intend from an existing code example. Donât âhauntâ them with phantom docs! đ»
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