A pet peeve of mine is example code with insufficient context. I can understand not wanting to bombard the reader with pages of code, but cutting down to the bone ends up sending them on an unwanted scavenger hunt.
When the scavenger hunt is through webpack config docs, it is especially unwanted.
The below example is from the NestJS documentation and shows how to include static assets in a build:
1
2
"assets": ["**/*.graphql"],
"watchAssets": true,
… What is that? What file are these props supposed to go in? Presuming it is a configuration file; where in the configuration object do they belong?
An improved version of this documentation might look something like this.
1
2
3
4
5
6
7
8
/* webpack.config.js */
module.exports = function (options) {
return {
...
"assets": ["**/*.graphql"],
"watchAssets": true,
};
}
With a couple extra lines it’s readily apparent 1) this is a web-pack config file 2) the added properties are in the root of the webpack config.
If we need more details, we can them up more quickly because the context has been provided. I can stop pulling my hair out. Leave that to my toddler.
Be kind. Add a smidge more context to your example code.