superscedes#18873

A few comments on the Usage Guide. I'm not sure its effective to switch between the "implicit" and "explicit" interface. It really interrupts the flow particularly when you explain the differences between the two quite a few times. I think maybe someone thought this would make it easier for people to transition between the two interfaces? But if it were me, I'd just write a separate tutorial for that.

I found it quit bizarre to go from line plots to a loving set of examples using pie charts of various complexities. That seems very out of place, and I don't understand what its doing there at all.

If I were in charge of this project, I'd

1. break this into two PRs! Because I suspect the style guide is "fine"/could be polished in follow ups
2. greatly simplify the "Usage Guide" and take out the pyplot stuff except to point towards somewhere we explain the difference.
3. If there is no where we explain the difference, write that as adifferent page, perhaps with an automatically generated large table that points out where the pyplot methods come from in the OO interface?

So I think@jklymak is making great suggestions, and if were starting from scratch would probably go that way, but I'm also not sure it should hold up this PR?

I think the style guide is an improvement. I'm not convinced that the usage guide is.

I agree with@jklymak. I propose to merge the style guide part now and meditate on the usage guide separately.

Happy to get the Documentation Style Guide in, though I'm not sure how to separate it from this PR. Originally, this project could have gone the route of two separate PRs, but I think for GSoD 2020 we went with the one for convenience.

As for the Getting Started guide, changes at that scale would take some time to unpack from its current state. That would likely be easier once the Style Guide is its own PR.

Happy to take guidance on next steps for this! I'm excited to see how it all turns out! Thanks everyone!

Just make a fresh branch from master and copy the new file and add it, commit, and make a new PR.

Since this Pull Request has not been updated in 60 days, it has been marked "inactive." This does not mean that it will be closed, though it may be moved to a "Draft" state. This helps maintainers prioritize their reviewing efforts. You can pick the PR back up anytime - please ping us if you need a review or guidance to move the PR forward! If you do not plan on continuing the work, please let us know so that we can either find someone to take the PR over, or close it.

Organisational remark: The style guide part is merged. And is the one producing the conflicts. It can be removed to put this in a clean state. I haven't look at the tutorial part and thus cannot comment whether it's worth reviving that.

haven't look at the tutorial part and thus cannot comment whether it's worth reviving that.

I think there's some good explanatory stuff there that might be worth integrating with the current guide, but the cleanest thing will likely be to open a new PR w/@jeromefv as a coauthor.