DOC: Merging the two indexing documents about numpy HOT 3 CLOSED

Hm it's a tricky question overall - I'm not very experienced with the diataxis framework so I get hung up on the differences between e.g. how-to and explanation etc., which makes it difficult for me to form an opinion on how various documents should be formulated.

Overall my opinion is: it makes sense to have an "indexing basics" article in the user guide that essentially explains the basics of multi-dimensional indexing, along with introducing the two basic indexing types (basic & advanced) and highlights the differences between the two. I also think de-duplication is a good goal - if there are going to be separate articles in both the user guide and reference manual, they should be complimentary rather than rehashing the same info twice.

Re: whether the articles should be formulated as explanations or how-tos ... 🤷 . My feeling is that it's important to have detailed information on the behavior of the various indexing types in the reference manual (as that's where one would naturally look for a deeper explanation of some indexing corner-case), but other than that I'm not really sure :)

from numpy.

Hi Mukulika!

I agree with Matti here; most of the concepts in the basics doc are already covered in the reference one. Apart from Combining index arrays with slices, the other unique sections seem to be Assigning values to indexed arrays and Dealing with variable numbers of indices within programs. We can let them remain in the basics documentation or include them in a new how-to for all types of indexing.

Agreed - that is a good starting point.

I feel that having a how-to instead of an explanation for ndarray indexing would make sense because users are more likely to want to know exactly how should they use indexing for their particular use-case. But again, I am not an experienced user so there might be a need for explanations too.

I think I would agree except that I'm not sure a how-to could cover most of the user cases (we would have to think this in more detail). But I think we could start with a draft for a how-to, and if we feel like there's a lot we want to expand on or the format doesn't fit, we can easily expand to an explanation.

If we want to keep the basics document, I would suggest renaming one of the docs. The basics doc could be renamed to Indexing basics, for example.

Sounds good!

@rossbar : the difference between a tutorial and a how-to is more on the end-goal: a tutorial aims to teach you bets practices and techniques (think teaching a child how to cook) and a how-to is more about getting something done (think recipe). Of course, Daniele himself constantly makes a point that Diátaxis is a suggestion and not a rule, and so these things don't have to always be taken 100% :)

from numpy.

But I think we could start with a draft for a how-to, and if we feel like there's a lot we want to expand on or the format doesn't fit, we can easily expand to an explanation.

That sounds good! I'll compile a list of use-cases soon.

For the time being, I'll rename and clean-up the indexing basics doc.

from numpy.