Tip 20 - add this code

Jul 13, 2024

Sometimes, writing docs is about predicting and avoiding things your readers can complain about.

When a reader is frustrated or confused using your project and they come to docs for help, it can be validating, or even satisfying, to say, “See! Even if I followed the docs, I would have got this wrong!” So, some of these tips fall into the broader category of “try not to give your readers ammunition.”

Admittedly, this helps me by having less negative feedback to deal with. But more importantly, it honestly does keep my writing more clear and helpful to the reader. (And, the only reason docs exist is to help.) Being precise in my writing helps my reader understand what I mean. It also helps them trust me, and my docs. I honestly cannot think of anything worse than reading a project’s official documentation and not knowing whether or not you can rely on it!

One PR suggestion I often make is to provide a code sample that works if copied into a project. It may not work for every reader’s particular use case, but it works in a particular situation that is explicitly stated:

✅ To deploy your Astro site at a particular path of your domain, provide a value for base. For example, to deploy your site at /docs, add base: '/docs' to your Astro config.
😐 To deploy your Astro site at a of your domain, add the following code to your Astro configuration: base: '/foo'.

The industry culture is to expect (much to my dismay) a reader to understand what foo and bar are doing in non-descript code examples. Given that, I contend that no one can reasonably complain about an example that says, “If you intend to do X, add code Y.”

Just adding an example with context puts you in the elite category of docs writers in my books! (And, since my personal accolades and gratitude are meaningless, measure your success by the lack of complaints you’ll get from your readers.)

“Add” means “paste” to your readers. If CTRL+V doesn’t literally, exactly, and immediately achieve a goal in their project, don’t say “add.” Instead, show your readers an example of how to do something in context, and let them extract the pattern. It’s helpful content, and great pedagogy!

See the whole list of tips!

Toggle Comments