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

docs: Add meta advice about questions (mostly for Discord) #179

Open
wants to merge 9 commits into
base: main
Choose a base branch
from

Conversation

kitten
Copy link
Member

@kitten kitten commented Oct 28, 2024

Currently, we're receiving a lot of messages on Discord that ultimately go unanswered. This often is caused by four main reasons:

  • The poster asked to ask
  • The poster asked about a solution without stating their problem
  • The poster waited to ask
  • The poster didn't give an issue report for an issue

This PR proposes to add three advice documents to this repo that can be used to reply to messages fitting the first three reasons above.

The fourth reason is excluded since it requires us to write a longer and more comprehensive document that would have to encompass a lot of advice on how to write a proper issue report (like an issue template++)

Most of these documents are based on existing docs that are out in the internet,
but have been rephrased to:

  • repeat the advice they contain and rephrase it at least once, since non-native speakers may read it
  • not antagonise the reader but be constructive instead
  • give them more actionable feedback
  • explain in more detail why they've been sent these documents

Don't ask to ask

This is a document for people that asked whether it's ok to ask, e.g.

  • "May I ask a question about EAS Builds?"
  • "Has someone worked with Expo Image?"
  • "Can someone DM me / talk to me about React Native project structures?"
  • "Would someone be willing to help me with my issue?"

Questions like these aren't actually asking a proper question, but are people asking to ask.
The document advice-dont-ask-to-ask.md tells them to try to instead form a full question or state their problem

Don't ask about solutions

This is a document for people that either have asked about a solution that isn't working, that we suspect are about to cause "the XY Problem", or are simply not stating their problem, e.g.

  • "I did [Y] and it did not work."
  • "How would I implement [Y]?"
  • "Would [Y] work and do [X]?"

Questions like these are either omitting all context on the original problem, are obscuring the problem, or are coming to a conversation with a solution without stating the full problem.
This often causes frustration on both sides, since the solution may either not be needed, not be the easiest, not be necessary, or is unrelated to the underlying problem.

Don't wait to ask

This is a document for messages that simply announce or precede a future question, e.g.

  • "Hi"
  • "Quick question"
  • "Anyone there?"

This is slightly distinct from "Don't ask to ask", since it may even happen several messages into a conversation. This happens when a poster is either looking for someone's undivided attention (which is unnecessary) or when they'd like to ease someone into a question.

Either way, this leads to unnecessary waiting time, and instead of combining an introduction with their question, they instead are prompting someone to respond first while then also making them wait for the actual question.

advice-dont-ask-about-solutions.md Outdated Show resolved Hide resolved
advice-dont-ask-about-solutions.md Outdated Show resolved Hide resolved
advice-dont-ask-about-solutions.md Outdated Show resolved Hide resolved
advice-dont-ask-to-ask.md Outdated Show resolved Hide resolved
@kitten kitten marked this pull request as ready for review October 29, 2024 14:21
Copy link
Contributor

@kadikraman kadikraman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some wording suggestions, otherwise looks good to me 👍

advice-dont-ask-about-solutions.md Outdated Show resolved Hide resolved
> You figured, you can solve `<X>` by doing `<Y>`.<br/>
> You ran into a problem with `<Y>` or don't know how to do `<Y>`.<br/>
> You asked for help with `<Y>`.<br/>
> Others help you with `<Y>` but are confused, because they don't know about `<X>`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> Others help you with `<Y>` but are confused, because they don't know about `<X>`.
> Others try to help you with `<Y>` but are confused, because they don't know about `<X>`.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's redundant?

advice-dont-ask-to-ask.md Outdated Show resolved Hide resolved
advice-dont-ask-to-ask.md Outdated Show resolved Hide resolved
advice-dont-ask-to-ask.md Outdated Show resolved Hide resolved

**If you're not sure what to ask, describe your issue.**

> Can someone help me with `<topic>`?<br/>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is definitely an example of how not to ask. I think these examples can be removed actually since we already have good examples in the Tl;DR

Copy link
Member Author

@kitten kitten Oct 29, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This quote is meant as one full message.
The problem here is it's probably hard to ensure this is all read as one message, but I can remove the newlines maybe.

I think this is still important since it tells people to write down:

  • the topic,
  • the problem,
  • what they tried,
  • what they expected to see,
  • what they saw instead

This is meant to be used as a full template, if the reader isn't sure how to phrase a full issue report

advice-dont-wait-to-ask.md Outdated Show resolved Hide resolved
advice-dont-wait-to-ask.md Outdated Show resolved Hide resolved
advice-dont-wait-to-ask.md Outdated Show resolved Hide resolved
advice-dont-wait-to-ask.md Outdated Show resolved Hide resolved
> - "How do I solve `<problem>` given `<context>`?"
> - "I tried `<solution>` because of `<problem>` while working on `<context>`. What is an alternative solution?"
> - "I ran into `<issue>`, when trying to do `<context>`. What's happening and what's a possible solution?"

Copy link
Contributor

@vonovak vonovak Oct 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think at this point it would be nice to have an example of a real (or rather made up but relatable) conversation (could be a screenshot?) that would demonstrate an example of this.

Actually, for all 3 of the documents I feel it'd be beneficial to have made-up examples that show what's GOOD and what's BAD.

A dummy example:

❌ (BAD) User A is asking about a solution which they decided is the solution for their problem:

<user A> "How do I replace the display on my iPhone?" 
<user B> "Do this and that"
<user C> "Why do you need to replace the display?"
<user A> "Because my iPhone screen is too dark to read."
<user C> "That's weird. Make sure to check the display brightness settings!"
<user A> "Ah, thank you, that fixed it!"

✅ (GOOD) Instead, describe your problem:

<user A> "My iPhone screen is too dark to read. What can I do?"
<user C> "Go to display brightness settings and turn it up!"
<user A> "Thank you, that helped!"

--

While all 3 documents explain the topics nicely, I'm worried that people who are sent over to them will feel overwhelmed by how much reading it is (edit: and give up on reading much of them).

@@ -1,7 +1,6 @@
# Don't ask about solutions[^1]

You may have been sent this document because **you asked about solutions** to a problem,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i only commented on it in this one place but it's like this in the entire doc

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will update to align 👍 (outside of GitHub comments and file editors ofc newlines shouldn't be reflected in formatting though luckily)

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

Successfully merging this pull request may close these issues.

4 participants