[RF-DOCS] Rewrite the Asset Pipeline Guide (#57181)
I've rewritten the guide with a bigger focus on how a developer would use the asset pipeline and Propshaft, rather than some of the inner workings.
A lot of detail was repeated and some bits were wrong. I've attempted to make the guide as concise as I could, and flow in the way a user would think about the asset pipeline.
Specifically, I'd like feedback about the diagram at the start of the guide. I'm not sure whether it's any good / helpful?
I've removed all info to migrate from Sprockets to Propshaft, instead linked to the migration guide in the Propshaft repo. I've also removed the section on `tailwindcss-rails` and instead linked to both that and `dartsass-rails`. It seems imbalanced to have a section on the Tailwind gem but not Dart Sass. Also since these are specific to certain libraries, I don't think they belong in the guide, and a link to their repos which has a Readme should be sufficient.
### Internal Audit
- The "After reading this guide, you will know:" intro doesn't mention Javascript or CSS at all. After reading it a newcomer isn't any wiser about what this guide explains. Maybe add "How to serve your Javascript and CSS assets" and "How to use bundlers for Javascript and CSS"
- The item "The main features of Propshaft, and how to set it up" is pretty tied to Propshaft (which I think is only a detail). I think we should make this a bit more libarary agnostic "The main features of the Asset Pipeline, and how to set it up." or maybe this should just be two separate items: "How to setup the Asset Pipeline" and "Using Propshaft for the Asset Pipeline".
#### What is an asset pipeline?
This section is more about Propshaft than the Asset Pipeline.
- It probably makes more sense if we describe the Rails Asset Pipeline instead of a more generic Asset Pipeline in the title (I don't think Asset Pipeline is a term used outside Rails). Maybe the title should be "What is the Asset Pipeline?" or "What is the Rails Asset Pipeline?"
- Maybe we can show a basic Asset Pipeline example where we show how an css file can get linked:
```
<%= stylesheet_link_tag "application", media: "all" %>
```
and gets turned into something like:
```
```
- The following sentence can get outdated outdated quickly. "Propshaft is built for an era where transpilation, bundling and compression are less critical for basic applications, thanks to better browser support, faster networks and HTTP/2 capabilities." It can probably just be removed.
- Maybe we should add a heading when it starts describing Propshaft?
- The first command we show in this guide is creating a new application without the asset pipeline. It feels kind of negative. Is that the first thing a reader would want to do? Maybe that section should be added to the Propshaft Setup section instead, after the regular install command.
#### Propshaft Features
- If you just jump to this section there is no description of Propshaft. I think the description of the previous section should be move here instead.
- It feels like this section describes some more advanced gotcha's that would be better described after the introduction to Propshaft in the next section. For example the "Asset Load Order" becomes clearer after the more simple "Setup" section in "Working with Propshaft"
- The numbered list of dependency strategies would probably be easier to scan as regular sections with titles.
#### Working with Propshaft
- "Working" in the title is pretty ambiguous. As this section is mostly about configuring Propshaft, maybe it should be renamed to "Configuring Propshaft"? Or, if we combine it with the previous section: "Using Propshaft for the Asset Pipeline"?
- The steps to setup Propshaft are bit hard to follow in a numbered list format. Maybe it should just be written as a regular section?
- The note ensuring that "the expected compiled filenames end with .js or .css." was a bit unclear to me.
It was changed from the following which had more context about `.sass` and
`.coffee`: https://github.com/rails/rails/blob/c3f2b545f86748c0e792ef0de3211f9d948b92a6/guides/source/asset_pipeline.md?plain=1#L673-L674
As Propshaft doesn't do full precompilation, I'm wondering if this whole section should be moved.
- Maybe the CDN section should be a separate top section? It's a pretty large section but not visible in the sidebar.
- `http://www.example/assets/application-d0e099e021c95eb0de3615fd1d8c4d83.css` isn't a valid URL, it should proabably be: `http://www.example/.com/assets/application- d0e099e021c95eb0de3615fd1d8c4d83.css`
#### Sprockets to Propshaft
- The section is mostly relevant for those that want to migrate to Propshaft. If you start a new Rails would anyone migrate from Propshaft to Sprockets? So I think this section should be called "Migrating from Sprockets to Propshaft".
- As the Bundling and Transpilation sections are also mentioned in the "Advanced Asset Management" top section I think it makes more sense to group them there (or at least have the extensively describe them there)?
- The "Evolution of Asset Management Techniques" and "Sprockets vs. Propshaft" sections basically both describe features from Sprockets that aren't supported in Propshaft. Maybe it should be grouped and renamed to something like "Unsupported features in Propshaft"?
- As this section is mostly about migrating to Propshaft I think it should be moved under the "Advanced Asset Management" top section. I think we should order sections on audience size:
1. Using basic propshaft (most readers)
2. Using advanced asset management (readers that want advanced features)
3. Migrating from Sprockets (readers that haven't yet migrated)
#### Advanced Asset Management
- The "How x Works" sections should at least use regular bullet points instead of numbered lists, as there is no actual order in the points. They should probably even be regular paragraphs with code examples for the different commands.
- The notes for cssbundling-rails and importmap-rails should be an actual NOTE or WARNING
- Maybe we can make the headings more descriptive, describing the use-case instead of the library names:
- jsbundling-rails -> "Javascript Bundling" or "Using Javascript Bundlers"
- cssbundling-rails -> "CSS Bundling" or "Using CSS Bundlers"
- tailwindcss-rails -> "Tailwind CSS integration"
- importmap-rails -> "Using Import Maps"
Co-authored-by: Petrik de Heus