-
Notifications
You must be signed in to change notification settings - Fork 0
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
DOC: Merging the two indexing documents #3
Comments
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 :) |
Hi Mukulika!
Agreed - that is a good starting point.
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.
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% :) |
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. |
commit 9c833bed5879d77e625556260690c349de18b433 Author: Thomas Li <47963215+lithomas1@users.noreply.github.com> Date: Wed Nov 17 16:21:27 2021 -0800 Add Windows config to GHA update script [wheel build] typo [wheel build] fix typo? [wheel build] fix linux builds? [wheel build] typo [wheel build] add license and pin to windows 2016 skip tests [wheel build] pin to windows 2019 instead [wheel build] try to find out the error on windows [wheel build] maybe fix? [wheel build] maybe fix? [wheel build] fix? [wheel build] cleanup [wheel build] Add Windows config to GHA update script [wheel build] typo [wheel build] fix typo? [wheel build] fix linux builds? [wheel build] typo [wheel build] add license and pin to windows 2016 skip tests [wheel build] pin to windows 2019 instead [wheel build] try to find out the error on windows [wheel build] maybe fix? [wheel build] maybe fix? [wheel build] fix? [wheel build] cleanup [wheel build] Update LICENSE_win32.txt Update LICENSE_win32.txt Add Windows config to GHA update script [wheel build] typo [wheel build] fix typo? [wheel build] fix linux builds? [wheel build] typo [wheel build] add license and pin to windows 2016 skip tests [wheel build] pin to windows 2019 instead [wheel build] try to find out the error on windows [wheel build] maybe fix? [wheel build] maybe fix? [wheel build] fix? [wheel build] cleanup [wheel build] Update LICENSE_win32.txt Update LICENSE_win32.txt Update cibw_test_command.sh commit 4bd12df Author: Thomas Li <47963215+lithomas1@users.noreply.github.com> Date: Mon Nov 15 17:28:47 2021 -0800 # This is a combination of 14 commits. # This is the 1st commit message: Add Windows config to GHA # This is the commit message #2: update script [wheel build] # This is the commit message #3: typo [wheel build] # This is the commit message #4: fix typo? [wheel build] # This is the commit message #5: fix linux builds? [wheel build] # This is the commit message #6: typo [wheel build] # This is the commit message #7: add license and pin to windows 2016 # This is the commit message #8: skip tests [wheel build] # This is the commit message #9: pin to windows 2019 instead [wheel build] # This is the commit message #10: try to find out the error on windows [wheel build] # This is the commit message #11: maybe fix? [wheel build] # This is the commit message #12: maybe fix? [wheel build] # This is the commit message #13: fix? [wheel build] # This is the commit message #14: cleanup [wheel build]
Continuing the discussion from numpy#14038:
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.
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.
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.Let me know what you think @melissawm and @rossbar!
The text was updated successfully, but these errors were encountered: