Tip 43 - what's in a name?

Aug 5, 2024

Naming is hard when creating features and designing APIs. But naming in docs examples can be fun and educational!

Code examples are… just that: examples. They are illustrative of larger concepts, not a function or configuration value you’ll be stuck with.

And, you’re limited in how many you can show. You can’t create examples for every situation your user might encounter while using your project. So, these examples need to help your reader make connections and form patterns to apply to their situation.

One PR suggestion I often make is to choose example file names that reinforce their use. It is helpful for readers to see the typical files and folder structure of your own project reflected in examples. This allows them to relate your examples to their own code.

You can squeeze even more meaning out of an example file name with a little creativity:

✅ excludedFiles: ['node_modules/chonky-module/not-this-huge-file.mp4']
😐 excludedFiles: ['files/subdirectory/foo.txt']

(Is “chonky” in your style guide? 😅)

This is also a safer way to inject a tiny bit of humour into your docs without “telling a joke.” Even if my reader doesn’t get the reference “chonky” (or why it’s hilarious, thank you very much), “huge” is descriptive without trying so hard.

This example still conveys a little extra meaning even if “huge” isn’t a familiar word. Media is a reasonable example of a potentially large file. Excluding items from the node_modules folder is also a common task my reader might perform.

Whether you go with the familiar and expected, or the unusual and whimsical, you can get “bonus docs” when you pay special attention to your example file names!

See the whole list of tips!

Toggle Comments