Doc: Updated transforms tutorial with key takeaways and bullet points#31324
Doc: Updated transforms tutorial with key takeaways and bullet points#31324anny0811 wants to merge 6 commits intomatplotlib:mainfrom
Conversation
Refined the paragraph explaining Transform objects and inverted() for better readability. No changes to the logic, just improved technical documentation.
melissawm
left a comment
There was a problem hiding this comment.
Hi @anny0811 - you have some failing tests to look at before the PR is ready for review. In particular take a look at the "line too long" failures.
But more importantly I think this may be a question of taste. Personally I like bullet points (they make the content easier to skim) but because there was no prior discussion of these changes in an issue, let's see what the maintainers think.
Cheers!
Co-authored-by: Melissa Weber Mendonça <[email protected]>
|
Hi @melissawm, I've fixed the long lines, but I'm still stuck with these last two linting/ruff errors. Could you please take a look? If it's a quick fix, feel free to update it, or just let me know where the issue is so I can fix it myself. I really want to ensure the PR meets the project's standards. Thank you for your help! |
|
IMO the easiest way to fix linting errors is to install the pre-commit hooks. In particular, trailing white space will be automatically removed for you. |
jklymak
left a comment
There was a problem hiding this comment.
I am not a fan of removing the paragraphs. Point form is fine when listing things, but this reads like an outline. I don't see how this has made anything more beginner friendly.
|
I think I misunderstood your original proposal on discourse. What I had been expecting was something like the key takeways anchoring the tutorial. I think here, subheadings anchoring what the long paragraphs are about + maybe some reordering might be in order. @anny0811 you may want to reverse outline the transforms tutorial to see if a cleaner structure falls out. |
|
If there is a relevant discourse discussion, it would be really helpful to link to that in the PR summary. |
|
Thanks for the feedback @jklymak and @story645. I understand the concern about the point form reading too much like an outline. I will restore the paragraph structure while adding clear subheadings to make the flow better, as suggested. I'll also try a reverse outline to see if a cleaner structure emerges. Thanks for the guidance! |
jklymak
left a comment
There was a problem hiding this comment.
I agree that the previous text could be improved, but in my opinion the rewrite doesn't add clarity, while at the same time being more verbose. This is an advanced topic, and I think someone who understand the transforms should rewrite this if there is a perceived need.
Also, having too many subheadings is just as bad as too few. Subheadings invite the user to skip to the section they think they are interested in. If we break that contract with the reader by then requiring them to go backwards to make sense of the current subsection, then we have not improved the reading experience. If we need paragraphs to be read in order, the topic sentence of the paragraph is the appropriate signpost.
I think this is b/c, as @anny0811 disclosed, she's using AI to help write this document. I think that's fundementally the wrong approach here since AI doesn't (can't?) know when it's seeing something that doesn't make sense b/c it's missing context. Which, the reason I'd suggested that a newcomer take a look is explicitly b/c I'd been hoping for a fresh eyes take on this document. |
|
I don't think this is a "newcomer" topic. I agree it could be simplified and made more "newcomer friendly", but it requires someone who understands the transform stack and its uses. |
I think this is a poor fit for someone new to matplotlib, but I think someone who is an experienced user and legitimately trying to understand the transform stack is better positioned to flag what's missing/unclear than someone who already knows what the document is describing. Mostly b/c I tend to learn things by writing about them. Unfortunately, I don't think that's what's happening in this PR, which seems to be various rounds of throw this doc at AI to "improve". |
|
⏰ This pull request might be automatically closed in two weeks from now. Thank you for your contribution to Matplotlib and for the effort you have put into this PR. This pull request does not yet meet the quality and clarity standards needed for an effective review. Project maintainers have limited time for code reviews, and our goal is to prioritize well-prepared contributions to keep Matplotlib maintainable. Matplotlib maintainers cannot provide one-to-one guidance on this PR. However, if you ask focused, well-researched questions, a community member may be willing to help. 💬 To increase the chance of a productive review:
As the author, you are responsible for driving this PR, which entails doing necessary background research as well as presenting its context and your thought process. If you are a new contributor, or do not know how to fulfill these requirements, we recommend that you familiarize yourself with Matplotlib's development conventions or engage with the community via our Discourse or one of our meetings before submitting code. If you substantially improve this PR within two weeks, leave a comment and a team member may remove the |
|
Hi @story645 and @jklymak, Thank you for the feedback. I realize that the transforms tutorial is quite advanced and my current approach with AI hasn't been effective. While I'm still eager to learn, I feel I might provide better value to the project by starting with a slightly more accessible documentation or code issue first. This would help me build a stronger foundation before tackling the transform stack. Would you happen to have a recommendation for a 'good first issue' or a simpler documentation task I could take on? |
I understand why you used AI instead of being honest about this being over your head, but frankly we're looking for a GSoC candidate who's not gonna waste maintainers time by putting in PRs they don't understand, so this behavior works against your application.
I point people to specific issues/PRs if I think it aligns w/ specific skills or interests they've mentioned b/c I do that for most new contributors, but you haven't mentioned anything specific on discourse. Look through the issues using the labels to filter. If you find something you're interested in, you're welcome to post on discourse to discuss it before putting in a PR. |
If we end up with a GSOC student working on transforms, perhaps this would be a good task for them towards the end of the summer. At that point they should have a good grasp of the subject but the learning would be recent enough to remember where the sticking points were. |
|
Thank you @story645 and @rcomer for the feedback. I appreciate the honesty. I realize now that my approach was wrong, and I'm committed to learning the right way by doing the work myself. I'll follow the advice to look through Discourse and filtered issues to find a better fit for my current skills. I hope to show better progress with my next contribution. |
PR summary
I have updated the transforms_tutorial.py to make it more beginner-friendly. I added a
"Key Takeaways" section and used bullet points to clarify the different coordinate systems (data, axes, figure, and display). This helps new users quickly grasp how transformations work in Matplotlib.
AI Disclosure
I used AI to help refine the language and the structure of the "Key Takeaways" section to ensure it is clear and professional.
PR checklist