DOC: Added a section in the 'Iterating over arrays' doc page on basic iteration. #16760
Conversation
|
Instead of explicitly duplicating "basic" iteration examples in the reference guide, how about linking to the relevant section of the tutorial instead? The advantage to such an approach is that it prevents fragmentation of the documentation, which can make things both hard to find for users and harder to maintain (see e.g. #14038) |
There was a problem hiding this comment.
I think going through and changing all of the heading styles makes this a more intrusive change than it needs to be. Rather than introducing a new heading, maybe the blurb you've added about "basic iteration" could be included as a .. note (or similar directive) at the top of the file?
…o the quickstart documentation section on basic iteration
b1c2fa0 to
4de4f33
Compare
There was a problem hiding this comment.
Thanks for sticking with this @dpitch40 , this is definitely an improvement IMO. I think you're right that the original document did not provide enough context and would be very confusing for newcomers who happened to stumble on this page looking for more basic usage/examples.
I've left a couple wording suggestions that you can feel free to use/ignore as you see fit (I think your original wording is fine) and took the liberty of pushing a minor rST-formatting nit to your branch.
Improve wording Co-authored-by: Ross Barnowski <[email protected]>
It seems strange that basic iteration over arrays is covered only in the Quickstart Tutorial and not mentioned in the reference doc page titled "Iterating Over Arrays". I normally only use the reference section and spent about ten minutes trying to remind myself of how basic iteration works/wondering if it had been removed in an update. This pull request adds a section on basic iteration and moves everything that was there down one header level.