Augment Getting Help docs.

[benjyw]

Lay out expectations for how to ask for help.

[huonw]

I like this in principle, thanks for taking it on

[huonw]

I strongly appreciate encouraging people to provide the right info straight up, but I'm a little concerned about phrasing some of this stuff too strongly in terms of "you must do all these things [or else you'll be ignored for process reasons]" which seems... scary, especially for someone new to open source.

I'd personally prefer to phrase it in terms of what's in it for the asker, i.e. focus on "help us help you" / "you'll fix your problem quicker if you make it easy for us to help".

For instance:

Suggested change

	You are far more likely to get a positive response if you demonstrate that you've put in the basic legwork first.
	You are far more likely to get a positive response if you make it easy for people to help you.

But I think potentially this whole section could be reframed slightly to be cast in that light, especially the list above.

What do you think?

[sureshjoshi]

Are there any projects that do this kind of language well (friendly, while direct and helpful?).

I'm always a fan of how Svelte phrases things, for example.

[huonw]

I'm always a fan of how Svelte phrases things, for example.

Ah yeah, I like it too.

Somewhat tangential but that text there makes me wonder if we could also update our bug report template to be more specific about what's expected.

Are there any projects that do this kind of language well (friendly, while direct and helpful?).

Good question! I don't know of any particularly good examples of the top of my head.

I know Rust (used to) put a lot of effort into helping new-comers, and this is their current "generic bug" issue template:

<!--
Thank you for filing a bug report! 🐛 Please provide a short summary of the bug,
along with any information you feel relevant to replicating the bug.
-->

I tried this code:

```rust
<code>
```

I expected to see this happen: *explanation*

Instead, this happened: *explanation*

### Meta
<!--
If you're using the stable version of the compiler, you should also check if the
bug also exists in the beta or nightly versions.
-->

`rustc --version --verbose`:
```
<version>
```

<!--
Include a backtrace in the code block by setting `RUST_BACKTRACE=1` in your
environment. E.g. `RUST_BACKTRACE=1 cargo build`.
-->
<details><summary>Backtrace</summary>
<p>

```
<backtrace>
```

</p>
</details>

[benjyw]

I'll just take this bit out.

[huonw]

Minor thing, but maybe this should be a numbered list:

Suggested change

	- First, do your best to solve the issue on your own. The Pants [source code](https://github.com/pantsbuild/pants), [issue tracker](https://github.com/pantsbuild/pants/issues), and [documentation](https://pantsbuild.org)
	1. First, do your best to solve the issue on your own. The Pants [source code](https://github.com/pantsbuild/pants), [issue tracker](https://github.com/pantsbuild/pants/issues), and [documentation](https://pantsbuild.org)

[huonw]

We could potentially also call out "provide support to others" as a useful activity, in addition to fixing issues.

[huonw]

In addition to the framing general concern, sometimes it's quite hard to create a reproducer, e.g. inconsistent things like pantsbuild/pants#19748, or performance issues at scale. Obviously a reproducer is helpful and really valuable, but it'd be unfortunate to completely discourage people from filing issues about those sort of things, at least as a place to have the community start "taking notes"/collaborating a reproducer.

I don't think we're at the scale of incoming issues where it's a major burden to encourage/remind users for a reproducer.

So suggestion for two actions:

• the phrasing of this to be something along the lines "provide a reproducer, or if not possible, all the information you can, e.g. pants.toml and relevant BUILD files"
• we (i.e. Pants maintainers) could start labelling such issues "requires reproducer" or something and then semi-regularly do a (manual) clean-up of such issues? E.g. if there's a bunch of unreproduced issues sitting around for a while, go through and close them.

Thoughts?

[sureshjoshi]

the phrasing of this to be something along the lines "provide a reproducer, or if not possible, all the information you can, e.g. pants.toml and relevant BUILD files"

What about some location (ticket, repo, whatever) where we have a set of common things we ask for (maybe something we could automate, anonymized into Pants CLI) - so, pants.toml, BUILD files, logs, neofetch data, etc... There would end up being a ton of superfluous data 🤷🏽

we (i.e. Pants maintainers) could start labelling such issues "requires reproducer" or something and then semi-regularly do a (manual) clean-up of such issues? E.g. if there's a bunch of unreproduced issues sitting around for a while, go through and close them.

OfficeJ auto-closes in 4 days, which is infuriating:

After an initial human triage of staleness, I'd be more open to a longer-running auto-close bot at like 3 months or something? I was looking at the issue backlog and seeing tickets that haven't been updated from mid-2018

[huonw]

What about some location (ticket, repo, whatever) where we have a set of common things we ask for (maybe something we could automate, anonymized into Pants CLI) - so, pants.toml, BUILD files, logs, neofetch data, etc... There would end up being a ton of superfluous data 🤷🏽

Putting it in a specific list of information to these docs might be a start?

OfficeJ auto-closes in 4 days, which is infuriating:

After an initial human triage of staleness, I'd be more open to a longer-running auto-close bot at like 3 months or something? I was looking at the issue backlog and seeing tickets that haven't been updated from mid-2018

Yeah, fully agreed: auto-closers are user-hostile. I'm thinking the label could be used for a human to go and find issues easily, and then close them out manually (or potentially not close them, e.g. if someone did provide a reproducer but it wasn't noticed). Pants doesn't receive that many issues 😄

[benjyw]

I don't think we're at the scale of incoming issues where it's a major burden to encourage/remind users for a reproducer.

Not sure about that. It is a frequent nuisance when people post questions lacking important information, or dump snippets directly into slack.

[benjyw]

PTAL

[benjyw]

PTAL, thanks!

[tgolsson]

Still think it's a bit harshly worded but I'm struggling to find alternatives.

Many issues, big or small, can be solved on your own or may have existing documentation. It is always worth checking the issue tracker, <...>. Even if you can't reach a complete solution, doing this groundwork is helpful and gives us [the community??] equal investment in helping you.

Maybe a bit wordy, and the end seems a bit robotic... not sure.

[benjyw]

Which part specifically seems too harsh? The "first try and solve it on your own" part?

[cognifloyd]

I think this might be a way to soften things.

[tgolsson]

Which part specifically seems too harsh? The "first try and solve it on your own" part?

Yes. I think the rest is good. Just this first sentence feels very condescending. I think it has this implicit assumption that the user doesn't try on their own without prompting. Like a quiz for school kids. "Give each problem a try before raising your hand".

[sureshjoshi]

Which part specifically seems too harsh? The "first try and solve it on your own" part?

Yes. I think the rest is good. Just this first sentence feels very condescending. I think it has this implicit assumption that the user doesn't try on their own without prompting. Like a quiz for school kids. "Give each problem a try before raising your hand".

I think Jacob's variant mitigates this well enough to put it up.

implicit assumption that the user doesn't try on their own without prompting

I think based on history, that does happen often though 🤷🏽

Calls to action work. About half of my feedback on Slack these past years has been a link to the docs, or a link to a prior Slack conversation - and that's basically it.

The people who would already dig through resources before trying to solve problems themselves will continue to do so, and those are are a bit less familiar with the codebase (or maybe development in general) can get a short list of good resources to take a crack at first.

And as lowly as I think of the current state/hype of and around "AI", this would be a picture-perfect use case for LLMs. Soak up all the docs and Slack history, weight it by recency and then allow users to type in a problem and point them to possible doc pages or Slack convos 🤌

In the meantime, I think a small, polite call to action + resources is pretty good.