Improvements to badge builder and listing

[paulmelnikow]

I'd like to propose some design changes to the badge builder and listing. There are two goals:

1. Make the badge listing easier to read:
   1. The entries should hint at what is inside, at the expense of documenting every possible option.
   2. Overall, the listing should avoid visual noise and reduce redundancy, at the expense of not showing full URLs.
2. Provide a richer experience on click:
   1. Include multiple examples.
   2. Allow any combination of options.

To achieve this, the idea is to aim to consolidate on a single pattern per service class with multiple examples.

• Continuing the direction of Drop-downs for multiple choice in patterns #2882, this implies a bit more rigidity on what is combined into one service, and what is kept separate. Some services may need to be combined or split up. (This can be done incrementally.)
• Some routes may need new redirectors so the main service can use a pattern.
• It's possible a few edge cases will require redirectors that have some degree of route prioritization. (I forget which these are. codeclimate?)

Changes to the builder

1. Optional parameter called out as such (already implemented but not turned on)
2. Show "optional" next to optional params.
3. Allow boolean params to default to either true or false.
4. Supports any combination of options.
5. Show a list of one or more filled-in examples.

Changes to the listing

1. Suppress the base URL.
2. Suppress the extension (partly in anticipation of SVG by default #2674, but that would be a separate effort).
3. Suppress any optional params.
4. Suppress multiple-choice patterns. :interval(dt|dw) becomes :interval.

Builder, combined into one:

List of examples:

The bottom of the model would show a bulleted list of examples, with full paths:

• /azure-devops/tests/azuredevops-powershell/azuredevops-powershell/1.svg
• /azure-devops/tests/azuredevops-powershell/azuredevops-powershell/1/master.svg
• /azure-devops/tests/azuredevops-powershell/azuredevops-powershell/1.svg?compact_message
• /azure-devops/tests/azuredevops-powershell/azuredevops-powershell/1.svg?failed_label=bad&passed_label=good&skipped_label=n%2Fa

As a "stretch goal," each of the URLs could have a Preview button next to it that updates the fields in the path and query string, and repopulates the live preview.

Listing:

Looking forward to feedback, as always!

[paulmelnikow]

For easy reference, here's what these look like now.

Builders (before):

Listing (before):

[chris48s]

Do you think we should just completely remove the paths/URLs from the listing?

We're now at a point where you can't easily copy them any more. Selecting the text opens a pop-up before you can copy it and then when you close the pop-up, you've lost the selection:

Given that, are they really doing anything useful? If not, we could just remove them, which would allow us to move to a narrower layout.

[paulmelnikow]

That's an interesting idea!

I do use them to search, but that's mostly because the titles are scrunched and hard to read.

I can see it being beneficial to copy and paste patterns. At one point I'd put the full pattern on the popup in #2496, though ended up removing it before it shipped. The bulleted list of example on the popup would be a good place to include the templated path (with click-to-copy).

The listing is useful for users who are working with e.g. an Azure Devops project and need to compare APIs across a service family. Though that doesn't seem super important.

As a shields dev, the full listings have been really useful for keeping the APIs in sync, though we could easily add a dev-facing page to take care of that.

I'm curious what the pages would look and feel like without them!

[chris48s]

I do use them to search, but that's mostly because the titles are scrunched and hard to read.

This is a good point. I think this could also be alleviated by improving the search feature.

The listing is useful for users who are working with e.g. an Azure Devops project and need to compare APIs across a service family.

As a shields dev, the full listings have been really useful for keeping the APIs in sync, though we could easily add a dev-facing page to take care of that.

Both of these are good points, and they both kind of come back to the issue that contributor use-case and end users use-case don't necessarily have to be served by exactly the same tools.

You're right that there are some other features that we need before we could drop it. Maybe its not worth it, but its an idea to consider.

Maybe its also a good thing to test or try and get feedback on. With website/front-end stuff like this (as opposed to badge logic/behaviour changes), I think there is more scope to crudely A-B test it by just changing stuff and seeing what happens. We could keep URLs in the data structure but remove them from the front-end and deploy for a few days.. If we get an issue with 50 👍s complaining about it, put them back. If nobody cares, we could probably safely lose them..

[paulmelnikow]

Both of these are good points, and they both kind of come back to the issue that contributor use-case and end users use-case don't necessarily have to be served by exactly the same tools.

👍

Maybe its also a good thing to test or try and get feedback on. With website/front-end stuff like this (as opposed to badge logic/behaviour changes), I think there is more scope to crudely A-B test it by just changing stuff and seeing what happens. We could keep URLs in the data structure but remove them from the front-end and deploy for a few days.. If we get an issue with 50 👍s complaining about it, put them back. If nobody cares, we could probably safely lose them..

True! We could also start with a toggle and see if we enjoy having it on or off.

[chris48s]

We have just launched a completely redesigned frontend https://shields.io/ including a new builder UI

Closing this issue as it relates to the previous frontend