Refactor support.md
#8
Conversation
github-actions
bot
added
👋 phase/new
| * make your question concrete, | ||
| zoom in; | ||
| explain what the actual problem is | ||
| * when you ask something specific, | ||
| zoom out; | ||
| explain the context of your question |
There was a problem hiding this comment.
this could maybe be rephrased, when I read this, I read it as do one or the other, not do both. Which I think is your intent.
There was a problem hiding this comment.
Indeed, it’s intentional, to ask for zooming in and zooming out. To ask for both.
I find myself asking for the context when folks are too specific. The typical XY situation.
And sometimes there’s wall of texts and very broad ideas of “lets change everything” and then I ask: ok but like what’s a practical solution?
I don’t mind someone reading this and wondering for a second, “wait, that’s a contradiction?!”
Any idea for how to improve this?
There was a problem hiding this comment.
What about something like:
* start with the big picture,
explain what you're trying to do and how it fits your project
* describe the specific problem,
what happens, what you expect, and include examples if possible
* explain why it matters,
how it impacts your work or goalsThere was a problem hiding this comment.
Thanks!
This to me seems too specific to bug reports / feature requests, code. Very streamlined. My intention with this list is more geared towards discussions. Arbitrary questions.
The bit on “and include examples if possible” also seems covered by the points “show the code, show what you tried” and “provide sample code: a markdown code block, CodeSandbox, StackBlitz, video”
I also dislike the word “start” here, I get that it exists to make sure both are done, but I don’t want to enforce that order of first this and only then continue on to the next.
I’m hoping for more of a “symbiosis” between someone writing their question, checking this list, and thinking: good point, I should do that too. Or so.
Can your initial point be solved by changing:
* make your question concrete,
zoom in;
explain what the actual problem is
-* when you ask something specific,
+* also,
zoom out;
explain the context of your questionThere was a problem hiding this comment.
@ChristianMurphy ping! :)
There was a problem hiding this comment.
This to me seems too specific to bug reports / feature requests, code. Very streamlined. My intention with this list is more geared towards discussions. Arbitrary questions.
We're a code project. 🙂
Almost every discussion is a feature request, bug report, or code.
If you really want to optimize to the sole non-code question we get a year, go for it I guess? 🤷
I also dislike the word “start” here, I get that it exists to make sure both are done, but I don’t want to enforce that order of first this and only then continue on to the next.
I quite like the word start here.
I don't want to read paragraphs of text before knowing what the big picture goal is.
I’m hoping for more of a “symbiosis” between someone writing their question, checking this list, and thinking: good point, I should do that too. Or so.
People do that anyway.
I don't think I've ever seen an issue or discussion that point by point follows the support guide.
There was a problem hiding this comment.
If you really want to optimize to the sole non-code question we get a year, go for it I guess? 🤷
Clicking those links in this guide and checking the first few discussions, I do see many.
Starting with MDX, https://github.com/orgs/mdx-js/discussions/2557 and https://github.com/orgs/mdx-js/discussions/2067 are clear examples. For micromark https://github.com/orgs/micromark/discussions/181 and https://github.com/orgs/micromark/discussions/177 are clear examples. For rehype, https://github.com/orgs/rehypejs/discussions/184.
What I want is to not optimize for bug/feature requests. This is support.md. Bug/feature already have a very strict issue template, and contributing.md.
I believe that bug/feature can be strict exactly because support is less strict.
People do that anyway.
I don't think I've ever seen an issue or discussion that point by point follows the support guide.
Indeed, that’s what I am trying to go with. This seems to contradict your previous point?
Indeed, folks do not follow an order in these points. They don’t start with the big picture. I think that’s fine, I think that’s great!
There was a problem hiding this comment.
Clicking those links in this guide and checking the first few discussions, I do see many.
Reading those discussions, most are code questions, asked in a round about way.
What I want is to not optimize for bug/feature requests. This is support.md. Bug/feature already have a very strict issue template, and contributing.md.
I believe that bug/feature can be strict exactly because support is less strict.
People use issues as the way to send bug reports and feature requests, without filling out the template.
Indeed, that’s what I am trying to go with. This seems to contradict your previous point?
No.
People read it, they just don't follow it to a letter.
So why not describe the ideal, and let them choose how much to follow it?
Indeed, folks do not follow an order in these points. They don’t start with the big picture. I think that’s fine, I think that’s great!
I disagree, it's often a wste of maintainer time.
But you seem to have made you mind up so 🤷
There was a problem hiding this comment.
Reading those discussions, most are code questions, asked in a round about way.
I am happy that it is possible to post these things without them being too structured. Thinking of these 4 out of 5 (remco answered one), they’re examples of the more happy conversations I have had with people. I worry your proposal (and intent behind them, enforcing more structure) will make it harder for people to ask questions with some agency. Having more pleasant interactions.
People use issues as the way to send bug reports and feature requests, without filling out the template.
I do not understand this?
This PR is about discussions (if broadened, all forms of support).
Issues (bug/feature) have very strict forms. Separate guides in contributing.md. It is not possible to open issues without filling out the template as blank_issues_enabled: false is used.
So why not describe the ideal, and let them choose how much to follow it?
Practically, I do not think starting with a broader context is the ideal. I think the broader context can follow too.
Conceptually, I also would rather not describe a fictional ideal that is never followed.
This conversation seems to stray from the earliest point in this thread.
For the conversation on structuring (some) discussions, perhaps #4 is better suited.
For this point, which was about disjunction, one bullet point or the other, I did propose another patch above. Perhaps you have an opinion on it, or can further riff on that text? Perhaps we can also ask @remcohaszing whether he shares your reading
There was a problem hiding this comment.
I don’t read the wording as contradicting, but I understand how it could. I think using the word also resolves that. Maybe append to this point something like: There may be a better alternative to solve it
| To help us help you, | ||
| please read through the following guidelines. | ||
|
|
||
| Please understand that people involved with this project often do so for fun, | ||
| next to their day job; |
There was a problem hiding this comment.
I like these statements. Why are they removed?
There was a problem hiding this comment.
The same as contributing.md, see also the PR description.
Instead of putting a welcome message, and important info (some of it as a “note” blockquote about the CoC), this is now split into an introduction here, and a section on “expectations” next.
Additionally, some of the wording was quite verbose. To help people ask questions. I reworded some prose to make it shorter and more “to the point”.
| * help us help you! | ||
| spend time framing questions |
There was a problem hiding this comment.
No need for exclamation marks. They mean shouting. This can be interpreted as positive if the intention is clearly enthousiasm, which I think you’re going for. It can also be interpreted as negative if the intention is even slightly ambiguous, which this is.
| * help us help you! | |
| spend time framing questions | |
| * Help us help you. | |
| Spend time framing questions. | |
| What are you trying to accomplish? |
I like using bullet points, but it also feels incorrect to make everything lower case instead of full sentences with proper capization. An exclamation point also ends a sentence.
There was a problem hiding this comment.
- I don’t think
!means shouting. That’s uppercase.!means excitement. I agree that they should not be overdone. But I think a few are fine. No!gets a bit boring. A bit monotonous. There is no excitement at all, solely the same tone - The insertion of
What are you trying to accomplish?feels different than the rest of the 2 phrases. I think the later bullet capture that. This bullet point is more about time. The more you put in, the more we can put in. - The capitals and dots get important when there are different sentences. True,
!typically also means a new sentence. How about:
| * help us help you! | |
| spend time framing questions | |
| * help us help you; | |
| spend time framing questions |
or:
| * help us help you! | |
| spend time framing questions | |
| * help us help you, spend time framing questions |
| * show the code, | ||
| show what you tried |
There was a problem hiding this comment.
This seems somewhat friendlier and removes duplicate use of the word show..
| * show the code, | |
| show what you tried | |
| * share the code, | |
| show what you tried |
| * search [discussions][github-search-discussions] and | ||
| [issues][github-search-issues] before opening something, | ||
| include links to what you find |
There was a problem hiding this comment.
We also tell people to not comment on old threads. Even if a problem is resolved for one user, another user with a similar issue might not be helped by the answer, either by use of language, lack of knowledge, or other factors.
I think we should either encourage or discourage people to comment on existing issues / discussions.
There was a problem hiding this comment.
I agree, that’s why I added this. Search, and if you find the same problem or a working solution use that, if you don’t, open a new one and link what you found.
| * make your question concrete, | ||
| zoom in; | ||
| explain what the actual problem is | ||
| * when you ask something specific, | ||
| zoom out; | ||
| explain the context of your question |
There was a problem hiding this comment.
I don’t read the wording as contradicting, but I understand how it could. I think using the word also resolves that. Maybe append to this point something like: There may be a better alternative to solve it
| a markdown code block, | ||
| [CodeSandbox][], | ||
| [StackBlitz][], | ||
| video |
There was a problem hiding this comment.
I’ve seen people unable to provide example code, because they don’t know how to use markdown code blocks, especially nested markdown code blocks.
``````markdown
`````markdown
````markdown
```js
console.log('hi!')
```
````
`````
``````Maybe we should use this opportunity to teach people about this?
There was a problem hiding this comment.
Good idea. I do not know what the best way to share that is. It seems out of place to put this very practical markdown tip into this high-level “how to ask questions” list.
Some people don’t know markdown. They don’t understand that they have to use backticks around an HTML tag. They don’t know how to put any code in a code block.
So then maybe we need a “how to use markdown” section
Initial checklist
Description of changes
hi! Same thing as before: removing some of the superfluous words.
The Expectations is from
contributing.md(#7).Especially the guide on how to ask question is new: these tips are really based on how people ask questions, and I hope this improves them!