Refactor README to be easier to read through

[ADTC]

Preview: https://github.com/ADTC/svgo/blob/patch-1/README.md

• Split up code blocks by moving text outside them. (This also ensures that the Copy function makes sense. See screenshot:)
  • 
• Remove the redundant list of default plugins and refer to the table instead.
• Sort the table of plugins alphabetically. (It's easier to scan for a plugin.)
  • I suggest maintaining the sort when adding new items.
• Replace the enabled/disabled code in Default column with just Yes or blank.
• Tabulate the "Other ways to use" section and remove redundant "as a/an".
• Correct the word Donators to Donors.
• Add a new section called Troubleshooting.

[drewbaker]

You should add a highlight about how SVGO strips the viewbox by default, as it seems to be a common confusion and time suck with people using SVGO. See: #1128

[ADTC]

@drewbaker thanks for the tip. It's been 2 months since the members made any movement on the project. I don't even know if my efforts to improve the README are in vain or not. I will await for a member to let me know that they are merging/interested to merge this PR before considering your suggestion.

Also, the issue of viewBox seems highly controversial. I will need to be extremely careful with the wording so as not include any opinion. (I've actually been hit by the issue myself and disabled the optimization. We disable it by default in all of our projects. It should be disabled by default and be an opt-in.)

[ADTC]

PS: I will probably not include any specific mention about the issue though, because the table of plugins already specifies Yes for including removeViewbox as default. Perhaps I can improve the description to change when possible to when the dimensions in viewBox match the width and height attributes. That may make sense, right?

[drewbaker]

Yeah I agree that it's "controversial" for sure. I also agree with your idea on better defaults.

However, it seems the best we can do is document this expected behavior in a way to save people the trouble. Some better wording of this is what I had in mind: "If you are here wondering why your SVG's no longer scale after using SVGO, it's probably because you need to set removeViewbox to false".

[ADTC]

Sounds good, but it will have to be a separate PR. It's outside the scope of this one (which only refactors the doc without adding new content). Thank you though. 🙂

[lzl124631x]

Just my 2 cents.

I will probably not include any specific mention about the issue though, because the table of plugins already specifies Yes for including removeViewbox as default

This is a commonly-met issue and usually it wastes minutes if not hours for people to find the right solution. It's hard for people to notice removeViewBox in the long table of plugins. Also, it might not be straightforward for people to correlate scalability issue with viewBox attribute especially for people who are new to SVG. I think it worth being highlighted in an FAQ section to help people save time.

Example:
Issue: My SVG is not scalable now.
Solution: Try setting removeViewBox to false.

Perhaps I can improve the description to change when possible to when the dimensions in viewBox match the width and height attributes

I appreciate this clarity! It's much more helpful than "when possible". But sadly this condition will still break scalability most of the time :( I even wonder if it's possible to link to a Google Form to let people vote for the default removeViewBox setting lol

[ADTC]

FAQ or Troubleshooting section sounds reasonable. It will be better with more than just one item though. Are there other frequently met issues?

[lzl124631x]

FAQ or Troubleshooting section sounds reasonable. It will be better with more than just one item though. Are there other frequently met issues?

I'm not sure. But given that this issue is frequently met, I think it's fine to just have one item in FAQ for now and we can add more going forward.

[ADTC]

Hi @deepsweet can I please ask for this to be merged in? Besides the original clean-up of README I have also added a Troubleshooting section, with the scaling issue as the first entry. I think this will help future visitors of the library and it will update in NPM/Yarn repository with the new info as well.

Thank you so much! ❤️

[ADTC]

@TrySound could you please try the checks again? Looks like it had a tar decompression issue.

Thank you.

[TrySound]

Awesome, good job!

[ADTC]

Thank you so much @TrySound 🥳 🎉