Skip to content

"Deep linking" disparate documentation resources together #8008

Open

Description

@TomNicholas

What is your issue?

Our docs have a general issue with having lots of related resources that are not necessarily linked together in a useful way. This results in users (including myself!) getting "stuck" in one part of the docs and being unaware of material that would help them solve their specific issue.

To give a concrete example, if a user wants to know about coarsen, there is relevant material:

Different types of material are great, but only some of these resources are linked to others. Coarsen is actually pretty well covered overall, but for other functions there might be no useful linking at all, or no examples in the docstrings.


The biggest missed opportunity here is the way all the great content on the tutorial.xarray.dev repository is not linked from anywhere on the main documentation site (I believe). To address that we could either (a) integrate the tutorial.xarray.dev material into the main site or (b) add a lot more cross-linking between the two sites.

Identifying sections that could be linked and adding links would be a great task for new contributors.

Activity

  1. JessicaS11 commented on Oct 11, 2023

    @JessicaS11
    Contributor

    Another concrete example that came up at today's office hours (#8220) was content related to apply_ufunc (thanks @amanbagrecha!).

  2. amanbagrecha commented on Oct 12, 2023

    @amanbagrecha
    Contributor

    Thanks @JessicaS11 for tagging me to this issue. I think this would be a good issue for me to pick up. Can you assign it to me @TomNicholas? I'd try to cross-link as many docs apart from what is mentioned here

  3. TomNicholas commented on Oct 12, 2023

    @TomNicholas
    MemberAuthor

    Hi @amanbagrecha ! We don't normally assign issues, but you're welcome to work on this! Feel free to tag me for reviews or if you have any questions 🙂

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions