-
Notifications
You must be signed in to change notification settings - Fork 342
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
base: main
Are you sure you want to change the base?
Conversation
Co-authored-by: Kadi Kraman <[email protected]>
There was a problem hiding this 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 👍
> 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>`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
> 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>`. |
There was a problem hiding this comment.
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?
|
||
**If you're not sure what to ask, describe your issue.** | ||
|
||
> Can someone help me with `<topic>`?<br/> |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
Co-authored-by: Kadi Kraman <[email protected]>
> - "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?" | ||
|
There was a problem hiding this comment.
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).
Co-authored-by: Brent Vatne <[email protected]>
@@ -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, |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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)
Currently, we're receiving a lot of messages on Discord that ultimately go unanswered. This often is caused by four main reasons:
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:
Don't ask to ask
This is a document for people that asked whether it's ok to ask, e.g.
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 problemDon'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.
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.
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.