How to improve documentation

[bholloway]

This issue is request for feedback regarding documentation.

Some of the items we currently have seem fairly necessary

• configuration reference
• migrating versions
• known issues

But there are some things we need to do much better in v4

1. problem statement - A lot of people use this loading without realising what is does or the problem it's solving. Which is fine, but a lot of issues blame this loader for some misconfiguration somewhere else. A better understanding of the problem this loader solves might avoid that. However explaining how url rewriting is absent from CSS preprocessors is difficult. It might be better explained by example with some narrative, maybe even as a blog post/article.

2. order of precedence - In v4 there are multiple source locations tested. We need a good explanation of how the loader works in this respect, so that people can recognise problems and change the order of precedence if necessary.

3. advanced usage - The "join" function is intended for advanced users. It's fairly convoluted since it's designed around an iterable. However the iterable allows costly operations, such as a file-system directory search, to be performed on-demand. This should make it relatively simple to demonstrate some basic file search "magic" that some users miss from version 2.

Open to feedback and other ideas.

[bholloway]

For item (1) I was looking to see if anything has been written in this subject since I last looked.

I found brief mention in webpack documentation. And then realised I had written it some time ago 😆 . I think it needs some updating.

[bholloway]

Some suggestions from Thinkmill people

• Communicate through examples

  • when you have $variable for assets then you don't need this loader
  • with relative path, no $variable then you use this loader

• What is the google search term? e.g. "why can't I have relative asset paths"

[ajfarkas]

I'd love to see more documentation on the join function in particular. I'm having a lot of trouble understanding how it interacts with the root value.

[bholloway]

I'd love to see more documentation on the join function in particular

Documentation (and some refactor) of the v4 join in #188.

Please feel free to participate in the PR.

[bholloway]

After merging #188 and publishing resolve-url-loader@4.0.0-alpha.3 the new documentation is considered minimally complete.

Let's consider that the baseline and continue the conversation here as needed to improve them.

[bholloway]

Merging #192 makes further improvements to the "advanced usage" docs and improves the API for the "join" function.

Tagged as resolve-url-loader@4.0.0-alpha.4.

[bholloway]

Released resolve-url-loader@4.0.0-beta.1.

Docs are in fairly good shape and are no longer blocking V4 release.

Further feedback is still appreciated here. 🙏

[bholloway]

Closing this issue as completed.

Doc changes in future can be discussed on case-by-case basis with fresh issue.