[docs][material-ui] Add explanations for the Progress page circular demos

[EOEboh]

Duplicates

• I have searched the existing issues

Latest version

• I have tested the latest version

Summary 💡

Hello, thanks for the opportunity to create this issue!

I have a bad developer experience while utilizing the demo documentation for the Progress API. I would love each demo to have detailed but concise explanations of WHAT NEEDS TO BE ADDED to implement that particular variant.

This should be done for each sections as it is with most of the other APIs. This also applies to both the Circular and Linear Progress APIs.

As a seasoned technical documentation writer and React engineer, I would love to propose this change through a PR, however I would love a go-ahead from the maintainers.

I look forward to hearing from you.

Examples 🌈

Motivation 🔦

Most developers are always on "work mode", what this means is that they need to know what a particular API does at the INSTANT they go through its docs.
This means they need to be able to highlight the differences in two API variants in terms of what they need to add or what they need to modify. Not just in the code snippet but in words too!

I use MUI library on a daily basis and over the years, I have come to appreciate this library as the best component library ever created in the React ecosystem. It would be an honour to be on this project. Thank you!

[danilo-leal]

Hey @EOEboh, appreciate you creating the issue! Your rationale makes a lot of sense to me, though I'm curious about what exactly is missing for you in this Circular Progress case? We can definitely add a short one-liner there to introduce the demo, but the code snippet below should give you an idea of how to get the component looking/behaving like that.

[EOEboh]

What’s missing is that to easily onboard new MUI users, we should adopt the same approach that was used by most of the other APIs; which is to add short lines of explanations above every example.

It may seem trivial but I believe it would go a long way, I referenced my person experience when using the Progress API for the first time.

@danilo-leal

[Harshhhh1701]

Can I take up this issue?

[danilo-leal]

Hey @Harshhhh1701, appreciate the desire to help here! I think this issue points to the opportunity to revise this entire page writing & demos altogether, which is part of an overarching initiative we've been planning for the Material UI docs.

We definitely could do it iteratively and just add a small descriptive sentence to introduce these demos, but I think tackling it holistically will be more fruitful! With that, I'm planning to open up a revision PR for this page soon!

[EOEboh]

I’m glad you’re looking into it. Please notify me when the revision PR is opened.

@danilo-leal