docs: fix redocly cli quickstart

[techstacksavvy]

What/Why/How?

Validated existing instructions, refined page copy with explanations of the utility of each task, and added a common initial task

Reference

Resolves #1517

Check yourself

• check the existing instructions still work
• improve the copy on this page, including something about why each task is useful
• add some additional common first tasks, such as defining a ruleset or bundling a file

[changeset-bot]

⚠️ No Changeset found

Latest commit: bbbb643

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[lornajane]

Thanks @techstacksavvy, this is an improvement already!

The first two sections are good, I just removed the part about cloning the starter repo since people probably don't want to do that if they already have an API description to use - it's there in the admonition as an optional resource.

For the final section, could you please revisit the example? We already have a rule that requires a summary (https://redocly.com/docs/cli/rules/operation-summary/) so users shouldn't be creating a custom rule for that. A better example might be "craft a custom ruleset" - get the users to add a redocly.yaml config file using the minimal ruleset and adding a couple of other built-in rules on top.

I would also like to have a "more resources" section at the end of the quickstart to send people to more resources in case they are interested. If you can add this as well, that would be excellent. (I added a commit to your branch so make sure you update before doing more editing, and let us know if you have questions!)