[Icons] Improve setup instructions

[dbu]

Q	A
Bug fix?	no
New feature?	no
Docs?	yes
Issues	https://symfony-devs.slack.com/archives/C01FN4EQNLX/p1743272426739939
License	MIT

i missed that i need the http-client installed, the bundle silently reduces functionality without it. i try to make it more clear what needs to be installed by mentioning the optional dependencies in the installation section, and by moving the http client hint to the "icon sets" section rather than having it in the middle of the syntax how to render icons.

[smnandre]

Could you use another type of block here, or even maybe just a paragraph?

I'd like to stay in line with the symfony.com documentation "standard", and only document here the strict minimum.

Too many information could give a false impression of complexity

It's a delicate art to not overwelm users with info when they do not need it yet, but also not falling in the opposite. (your issue is a proof of that!).

[dbu]

my thinking was that the optional dependencies are easy to overlook when not reading through the complete documentation chronologically. if the introduction explains what the component can do and what you need to install to do that, i think it is useful.

i can change this into a sub-paragraph if you think that is better - i felt it being so short an additional title is not necessarily helping. on the other hand, the title will show up in the ToC so it might get useful visibility when starting to look for reasons of the problem.

[smnandre]

I understand your point of view. At the same time, I also have to consider the appeal of the documentation — first impressions matter.

If I land on a page that opens with multiple blocks of install commands, bash snippets, and config files, my first thought is often: "Wow, this package looks complicated to install."

But in this case, the vast majority of developers installing UX Icons just need to run composer req symfony/ux-icons, and everything is set up automatically.

I'm not saying we should ignore those who fall outside that category — but I also can't disregard the majority.

[dbu]

of course, having a 15 step installation instructions is off-putting. but oversimplification is not helping either. i removed the part about ux-twig-component and made a separate subtitle for the http-client

[smnandre]

If it's that visible, maybe then we can remove it from the other parts ?

This use case is not the most common, and I'm not 100% convinced it requires multiple big blocks on the same page.

[dbu]

honestly i think if we find a good solution for #2667, we can remove either this section or the ones below in the sections that rely on http client.

[smnandre]

(at least for the twig component thing that really does not deserve this highlight)

[Kocal]

Following https://symfony-devs.slack.com/archives/C01FN4EQNLX/p1743272426739939, I don't remember if this topic was already evoked, but maybe we can improve the DX and always register the commands ux:icons:search and ux:icons:import, but throw at runtime if symfony/http-client is not installed?

[kbond]

maybe we can improve the DX and always register the commands ux:icons:search and ux:icons:import, but throw at runtime if symfony/http-client is not installed?

That's a great idea!

[dbu]

i try to improve the exception when no icon is found and the http client is not available in #2667

with that we could consider leaving the setup instructions as is - although imho its not the greatest DX to install something and then get an error telling i need to install something more.

[dbu]

the two times HTML syntax is introduced

made me realize: the first parts of the section Rendering Icons are repetitions without added information of Loading Icons and the rather randomly appearing HTML Syntax section. i think that is confusing. i suggest to supress the first HTML Syntax section.
Rendering Icons also does not mention attributes anymore, which seems odd to me as it is the "reference" part about rendering.

[kbond]

This looks good to me. We can iterate as needed.

[smnandre]

Does feel like a duplicate of the tip 10 lines below.

What about moving it after the introduction sentence ? and before the code examples ?

[dbu]

i duplicated it on purpose, becaues it is very important, and i think some people will rather see the box, while others rather read the text flow. alternatively we could even put it into the code block as a comment right before the first tag.

which introduction sentence do you mean? the "HTML Syntax" section only has one sentence until here? or you mean moving the ..tip to above the code? i can also do that.

[smnandre]

LGTM and we'll improve it if/when we implement an in-code solution

[kbond]

Thanks David.