On some unclear Documentation and outdated Plugins

[KilianKilmister]

Documentation Is:

• Missing
• Needed
• Confusing
• Not Sure?

Please Explain in Detail...

three points:

• for one: a large portion of the plugins listed in rollup/awesome are outdated, broken and no longer maintained. will be picked up again on rollup/awsome
• second: the documentation on the @rollup/plugin-html plugin is very confusing. it is unclear how and where to use the templateoption.it would be awesome if an examle configuration or project could be added, since apparantly non of the community plugins for HTML seem to be maintained and/or well documented. might be picked up again on rollup/plugins
• and lastly: the documentation on the API seems a bit convoluted. especially since it's not very well seperated from the standard config-file usage and how the function for loading config files is to be used is lost on me.

Your Proposal for Changes

• for the first point it would be awesome if the community plugin list could be stripped down to exclude outdated and broken plugins. I understand that this is timeconsuming, but it would make a lot easier for people new to this topic. As plugins can be a great tool to learn, it's suboptimal having to find out multiple times, that the installed and configured plugin simply doesn't work and it's issue page goes unanswered
• second: as mentioned something like an example config/repo would be great, and maybe some rewording of the docs for newcomers.
• third: some basic restructuring of the API docs. for example how the section of loading config files is packed onto the end of watch.options is not wery helpful. Now it is very detailed, i have to say.
  the API can be such a great tool to integrate into your workflow and a lot of things people are using plugins for can be done with the API and some simple JS.
  rollup is a great tool, it's just quite overwelming if you are new to webdevelopment.

[shellscape]

for one: a large portion of the plugins listed in rollup/awesome are outdated, broken and no longer maintained.

You have the wrong repo. Please open a separate issue at https://github.com/rollup/awesome. As the sole maintainer of that particular repo though, please open a PR to correct bad links, or point out which dead projects are in the README in an issue. That repo is maintained by community action and rarely has direct edits. Fwiw, plugins which are still available, but unmaintained, are still valid. If the author states that the project is dead, then we allow their removal. As you're asking for our time to weed that list for you, I would suggest donating your time to pitch in and help others like yourself.

second: the documentation on the @rollup/plugin-html plugin is very confusing. it is unclear how and where to use the templateoption.it would be awesome if an examle configuration or project could be added, since apparantly non of the community plugins for HTML seem to be maintained and/or well documented.

You have the wrong repo. Please open a separate issue at https://github.com/rollup/plugins. I'm really confused how anyone could find that documentation confusing. It creates an html file. If all else fails, always look to the tests https://github.com/rollup/plugins/tree/master/packages/html/test. This may be one that just needs a little leveling-up on bundler basics before consuming plugins that work with the output.

and lastly: the documentation on the API seems a bit convoluted. especially since it's not very well seperated from the standard config-file usage and how the function for loading config files is to be used is lost on me.

A lot of work was done on this a while back to make it friendly to newcomers. Though we can't suit everyone's tastes, comprehension (not meant as a dig), or preferred reading style, we get very few complaints. I would suggest being specific about which parts you find confusing, which would allow us to take a closer look at what might be throwing you for a loop.

[KilianKilmister]

First off: my apologies. I didn't think of filing these issues in their respective repos. That's on me.
I will file them in the correct place.

I also feel that my choice of title made the issue i opened seem more critical than it actually was. The second and third point were meant about Small specific parts that i simply wanted to add as i was allready filing an issue.

• About /Awesome: I'll do a pass and provide details on the once i feel are outdated in a new issue/PR over there.

• About /plugins: to get the basics working was an absolute breeze. It was only about the Template option that was uncelar. I did take a look at the tests when i first tried to figure it out. but they are rather spase, without comments and different file-naming. But i will take another pass at it, and would then go to something like stack-exchange. that way i might get an answer that i could offer as an improvement to the docs.
  These two points are a bit hard to judge for me as a newcommer to the web-side of JS, but i'll do what i can.

now to what actually belongs in this repo:

Dont get me wrong. The vast majority of the documentation is excelent. It's only the API section, that i think came a little short. I will go over it and pull some specifics and append them to this thread. It also kind of threw me off, how the documentation recommends against using the api:

Rollup provides a JavaScript API which is usable from Node.js. You will rarely need to use this, and should probably be using the command line API unless you are extending Rollup itself or using it for something esoteric, such as generating bundles programmatically.

Having taken a second look at that paragraph, it makes absolute sense to include it. because yes, it's much easier for a newcommers to use the CLI with a config file. From the way i'm used to doing these things i headed streight for the API. And i do feel that that section fell little short in the docs.
But as i said, I'll pull some of the less clear parts and go in to detail at a later point.