Skip to content
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

Closed
Mukulikaa opened this issue Jun 15, 2021 · 3 comments
Closed

DOC: Merging the two indexing documents #3

Mukulikaa opened this issue Jun 15, 2021 · 3 comments

Comments

@Mukulikaa
Copy link
Owner

Continuing the discussion from numpy#14038:

I would remove the "Single element indexing", "Other indexing options", "Index arrays", "Indexing Multi-dimensional arrays", "Boolean or “mask” index arrays", and "Combining index arrays with slices", but make sure the content exists on the reference page.

The information you remove from the user page about mixing indexing types should be merged in under Advanced Indexing".

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!

@rossbar
Copy link

rossbar commented Jun 16, 2021

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 :)

@melissawm
Copy link

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% :)

@Mukulikaa
Copy link
Owner Author

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.

Mukulikaa pushed a commit that referenced this issue Jan 1, 2022
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]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants