search

bholloway / resolve-url-loader

Webpack loader that resolves relative paths in url() statements based on the original source file
563 stars 71 forks source link

How to improve documentation #163

Closed bholloway closed 3 years ago

bholloway commented 3 years ago

This issue is request for feedback regarding documentation.

Some of the items we currently have seem fairly necessary

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 commented 3 years ago

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 commented 3 years ago

Some suggestions from Thinkmill people

ajfarkas commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

Closing this issue as completed.

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