Proposal:

Use ax.set_thing() as a baseline. These are well-known and less experienced people who only learn one interface can discover it easily and can potentially do everything with it. Consider and teach ax.set() as a shortcut that can be used to collect multiple set_ * into a single command. IMHO this is enough level of detail for the end user.

Our docs, have higher bar on being understandable and instructive. I therefore would be a bit more specific. As rules of thumb for the matplotlib docs:

• Use set() if you want to set multiple similar properties (and don't need additional parameters), e.g.
  • set(xlim=..., ylim=...)
  • set(xlim=..., xlabel=...)
  • set(xlabel=..., ylabel=..., title=...)
  • set >= 3 properties
• Do not use set() for
  • single properties, e.g. set(title=...)
  • two properties that are very different, e.g. set(title=..., xlim=...) - saving one line is not worth the reduced clarity of doing two very different things in one call.

I agree that set_thing is canonical and set is a shortcut. I think whether the shortcut is appropriate for a particular use-case is up to the user to decide.

For the docs/examples, I think @timhoffm and @story645 both make good arguments in opposing directions and I do not know how to choose between them! So I would vote for not codifying this but instead leave it up to individual authors and their reviewers. This also fits my general preference for not making the contributors’ guide any larger than it needs to be.

This also fits my general preference for not making the contributors’ guide any larger than it needs to be

My preference for consistency in the docs means I'm okay w/ the decision not going in my favor, and i think adding this to an entry in the style guide would be OK? I see that as sorta the doc equivalent to the PR guidelines, more for maintainers than contributors, but also means then we don't have long discussions about it on every PR.

I also agree w/ you very much that really it's so very case dependent. I think Tim's first bullet is a good compromise:

set >= 3 properties

Anything more than about 2 properties and the set_* boilerplate starts getting overwhelming and distracts from the purpose of the example, two very different properties or just one property and use of set might be what's distracting.

two properties that are very different, e.g. set(title=..., xlim=...) - saving one line is not worth the reduced clarity of doing two very different things in one call.

I love highlighting that set works for all the things & is the wonderful all the things function folks want.