Docs: Add figure for navigating help resources

[JessicaS11]

• Addresses Where do I go for help with...? Figure #8990
• User visible changes (including notable bug fixes) are documented in whats-new.rst

[max-sixty]

Very cool! Thanks @JessicaS11

Couple of suggested changes (maybe others will disagree, I see a draft of this was reviewed in the discussion):

• Can we add a line directly from having a bug or type to PR? No need for folks to open an issue for something small.
• Possibly PRs should be inside the contributions box?
• Add LLMs as an option in "How do I use Xarray"?
• I actually don't think it's helpful to ping issues. PRs are waiting on maintainers, but issues need contributions not reminders, so I'd remove that arrow.
  • Pinging can just be "Gentle ping", no need to @ an individual (and not sure how they'd know who to @...)

[JessicaS11]

Readthedocs is failing with: fatal: reference is not a tree for the last commit. I'm assuming this is somehow caused by the way I added to the PR, but I'm also not sure how to fix it. To add to the PR after the precommit.ci commit, I ran git fetch upstream pull/9147/head:help-figup and git rebase db637420 before git push origin help-fig:help-fig. Is there another way to do this that won't upset readthedocs?

[keewis]

looks like that was just a temporary hiccup: https://readthedocs.org/projects/xray/builds/24763397/

[JessicaS11]

Couple of suggested changes (maybe others will disagree, I see a draft of this was reviewed in the discussion):

Thanks for sharing these - I'll commit once I've addressed them all.

* Can we add a line directly from having a bug or type to PR? No need for folks to open an issue for something small.

I'll update these

* Possibly PRs should be inside the contributions box?

Good call!

* Add LLMs as an option in "How do I use Xarray"?

Done!

* I actually don't think it's helpful to ping issues. PRs are waiting on maintainers, but issues need contributions not reminders, so I'd remove that arrow.

I guess I was thinking the case where the issue is a proposal that needs "approval" or feedback for the contributor to work on and get to the point of submitting a PR. Bug report issues aren't generally going to be "quiet" because maintainers are likely to be working on fixing them.

  * Pinging can just be "Gentle ping", no need to @ an individual (and not sure how they'd know who to @...)

What is a "gentle ping" then? Simply posting a comment in the PR?

[max-sixty]

What is a "gentle ping" then? Simply posting a comment in the PR?

Sorry, yes, I'm not sure the best wording, I was thinking fab:fa-github Gentle ping! might be a nice informal way of showing it, but maybe that's confusing, feel free to riff...

I guess I was thinking the case where the issue is a proposal that needs "approval" or feedback for the contributor to work on and get to the point of submitting a PR. Bug report issues aren't generally going to be "quiet" because maintainers are likely to be working on fixing them.

IME it's quite rare that things need approval to get started, at least in projects like xarray. And there are almost 1000 issues so pinging for updates is somewhat disruptive.

So I would probably:

• add an arrow from the root to contributors' guide "I'd like to make a small change"
• drop the "my plan was approved"
• switch "I found a bug or typo" -> "I found a bug"

Is that OK? I don't mean to be wordsmithing. (It's actually quite interesting to have to make legible lots of implicit understanding of how to operate.)

[JessicaS11]

Is that OK? I don't mean to be wordsmithing. (It's actually quite interesting to have to make legible lots of implicit understanding of how to operate.)

It's great - I completely agree on the making explicit the implicit being an interesting exercise.

I went with "Comment on your PR" - to me a "ping" means an @ mention or Slack/email message (basically explicitly contacting a group or individuals), which I'm sure is one of many definitions people have for it!

[max-sixty]

I think this is looking really good! Thanks @JessicaS11 !

[JessicaS11]

I think this is looking really good! Thanks @JessicaS11 !

Thanks! I'm going to see if I can get it to render properly in the docs before merging (hence ongoing changes). Right now it's building successfully but showing up as text...

[JessicaS11]

Hey team - I'm hitting a wall here on how to get this rendered. Specifically, it appears the sphinxcontrib.mermaid extension uses an older version of mermaid (10.2.0) than the mermaid.live editor I used to create the flowchart (10.9.1). As a result, there are syntax errors. My understanding of the solution pathways are:

1. get the current flowchart code to work in an older version of Mermaid (not sure of an easy way to do this).
2. build the diagram and include it in the docs differently (e.g. using mermaid-cli), which I don't understand how things are built under the hood well enough to execute on my own (see also my attempt to get such a figure into the xarray-tutorial, though there was discussion of moving that to the docs as well: update backends tutorials intro xarray-contrib/xarray-tutorial#266)

Any help or insight is greatly appreciated!

[dcherian]

I found a setting to set a custom mermaid version: https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/#config-values

[JessicaS11]

I found a setting to set a custom mermaid version: https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/#config-values

@dcherian Thank you!!