This issue is to rewrite parts of usage.rst to maintain the desired flow.
In #480 , I added new sections to docs/source/usage.rst: "Capturing Screenshots" and "Accessing Pixel Data". These were intended to give a narrative description of how to use MSS, in addition to the existing example-based descriptions.
In #566 , we added a detailed description of the Monitor class and how it works to those. However, I felt like the new text didn't fit in well with the existing flow. My objection at the time says:
This "Capturing Screenshots" section is meant to be a "how to get started" introduction to MSS. It tries to focus on the essentials, and avoid confusing new users.
With that in mind, most of this seems to be just an unnecessary distraction. It increases the cognitive load on new users. For instance, are new users who are just learning the basics likely to care that **monitor unpacking is not supported? It's just extra stuff that they don't have to care about, but still have to spend cognitive cycles to decide if they care.
For the purposes of this flow, I think that explaining all about a Monitor object may be a bit too much. I might suggest putting the details in a separate section or subsection, or even just using some cross-references into the API reference for some details. Putting some of this into a separate section can help with cognitive chunking, and let the user get a basic flow before trying to absorb a lot of the details.
I didn't address this in #579 , since I was focusing on the specific issues I'd already proposed fixes for. In a separate conversation, I mentioned this to @halldorfannar , and he agrees it would be good to rewrite the relevant parts of usage.rst accordingly. I volunteered to do that rewrite.
You can assign this issue to me.
This issue is to rewrite parts of
usage.rstto maintain the desired flow.In #480 , I added new sections to
docs/source/usage.rst: "Capturing Screenshots" and "Accessing Pixel Data". These were intended to give a narrative description of how to use MSS, in addition to the existing example-based descriptions.In #566 , we added a detailed description of the Monitor class and how it works to those. However, I felt like the new text didn't fit in well with the existing flow. My objection at the time says:
I didn't address this in #579 , since I was focusing on the specific issues I'd already proposed fixes for. In a separate conversation, I mentioned this to @halldorfannar , and he agrees it would be good to rewrite the relevant parts of
usage.rstaccordingly. I volunteered to do that rewrite.You can assign this issue to me.