One thing I've learned writing documentation (and struggling) is that, when you find yourself writing at length, splitting text into sections, and peppering a copious amount of examples, you need to stop and do 2 things:

- Audit for conciseness

- Add a tl;dr summary at the top

And I do wish this had a real example it was playing with, and it consistently used that same example all the way through as it built the layers of what the problem being solved with decorators is. It's a lot easier to teach a concept when you can contextualize it in a way that's shows it's usefulness.

I'm not sure if this metric really matters, but this is wordier than the PEP that describes decorators.