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.

Sign up for GitHub

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

Refactor support.md #8

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

Refactor support.md #8

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2254631
Refactor `support.md`
wooorm Nov 21, 2024
4215189
Remove double anticipation
wooorm Nov 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 79 additions & 103 deletions support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,130 +1,106 @@
# Support

> This project has a [code of conduct][coc].
> By interacting with this repository,
> organization,
> or community you agree to abide by its terms.

Hi!
👋
We’re excited that you’re using **unist** (**syntax-tree**) and we’d love to
help.
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;
Comment on lines -12 to -16
Copy link
Member

Choose a reason for hiding this comment

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

I like these statements. Why are they removed?

Copy link
Member Author

Choose a reason for hiding this comment

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

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”.

you are not entitled to free customer service.
Take a moment to read the following guidelines.
Thanks for using our work!

## Contents

* [Questions](#questions)
* [Asking quality questions](#asking-quality-questions)
* [Expectations](#expectations)
* [Contributions](#contributions)
* [Where to ask questions](#where-to-ask-questions)
* [How to ask questions](#how-to-ask-questions)
* [License](#license)

## Questions

Please chat and ask questions on [Discussions][chat]!
Jump in there and lurk,
talk to us,
and help others.

* **[unified](https://github.com/unifiedjs/unified/discussions)**
— topics relating to **[unified][]** in general
* **[remark](https://github.com/remarkjs/remark/discussions)**
— topics relating to the [remark][] ecosystem,
markdown,
and **[mdast][]**
* **[rehype](https://github.com/rehypejs/rehype/discussions)**
— topics relating to the **[rehype][]** ecosystem,
HTML,
and **[hast][]**
* **[retext](https://github.com/retextjs/retext/discussions)**
— topics relating to the **[retext][]** ecosystem,
natural language,
and **[nlcst][]**
* **[MDX](https://github.com/mdx-js/mdx/discussions)**
— topics relating to **[MDX][]**
* **[micromark](https://github.com/micromark/micromark/discussions)**
— topics relating to the future of markdown in unified!
* **[vfile](https://github.com/vfile/vfile/discussions)**
— topics relating to **[vfile][]**: virtual files
* **[syntax-tree](https://github.com/syntax-tree/unist/discussions)**
— topics relating to **[syntax-tree][]** and **[unist][]**

### Asking quality questions

Help us help you!

Spending time framing a question and adding support links or resources makes it
much easier for us to help.
It’s easy to fall into the trap of asking something too specific when you’re
close to a problem.
Then,
those trying to help you out have to spend a lot of time asking additional
questions to understand what you are hoping to achieve.

Spending the extra time up front can help save everyone time in the long run.

* try to define what you need help with:
* is there something in particular you want to do?
* what problem are you encountering and what steps have you taken to try
and fix it?
* is there a concept you’re not understanding?
* learn about the [rubber duck debugging method][rubberduck]
* avoid falling for the [XY problem][xy]
* search on GitHub to see if a similar question has been asked
* if possible,
provide sample code,
a [CodeSandbox][],
or a video
* the more time you put into asking your question,
the better we can help you

## Contributions

See [`contributing.md`][contributing] on how to contribute.

## License

This document has the following license:
[CC-BY-4.0][license] © [Titus Wormer][author]

[license]: https://creativecommons.org/licenses/by/4.0/
## Expectations

[author]: http://wooorm.com
This community has a [code of conduct][file-code-of-conduct].
You must follow it when interacting with the community.

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
Be respectful and considerate when asking for things.
You are not entitled to free customer service.

[vfile]: https://github.com/vfile
Be friendly!
Be excellent to each other.

[syntax-tree]: https://github.com/syntax-tree

[unist]: https://github.com/syntax-tree/unist
## Contributions

[mdast]: https://github.com/syntax-tree/mdast
See [`contributing.md`][file-contributing] on how to contribute.

## Where to ask questions

Each organization has a discussion forum:

* [`mdx`](https://github.com/orgs/mdx-js/discussions)
— markdown for the component era
* [`micromark`](https://github.com/orgs/micromark/discussions)
— underlying markdown parser
* [`rehype`](https://github.com/orgs/rehypejs/discussions)
— HTML ecosystem
* [`remark`](https://github.com/orgs/remarkjs/discussions)
— markdown ecosystem
* [`retext`](https://github.com/orgs/retextjs/discussions)
— natural language ecosystem
* [`syntax-tree`](https://github.com/orgs/syntax-tree/discussions)
— ASTs:
estree,
hast,
mdast,
nlcst,
unist,
xast
* [`unified`](https://github.com/orgs/unifiedjs/discussions)
— core of the ecosystem
* [`vfile`](https://github.com/orgs/vfile/discussions)
— virtual file format

## How to ask questions

* help us help you!
spend time framing questions
Comment on lines +60 to +61
Copy link
Member

Choose a reason for hiding this comment

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

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.

Suggested change
* 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.

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 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:
Suggested change
* help us help you!
spend time framing questions
* help us help you;
spend time framing questions

or:

Suggested change
* help us help you!
spend time framing questions
* help us help you, spend time framing questions

* show the code,
show what you tried
Comment on lines +62 to +63
Copy link
Member

Choose a reason for hiding this comment

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

This seems somewhat friendlier and removes duplicate use of the word show..

Suggested change
* show the code,
show what you tried
* share the code,
show what you tried

Copy link
Member Author

Choose a reason for hiding this comment

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

sure 👍

* search [discussions][github-search-discussions] and
[issues][github-search-issues] before opening something,
include links to what you find
Comment on lines +64 to +66
Copy link
Member

Choose a reason for hiding this comment

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

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.

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 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
Comment on lines +67 to +72
Copy link
Member

Choose a reason for hiding this comment

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

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.

Copy link
Member Author

Choose a reason for hiding this comment

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

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?

Copy link
Member

Choose a reason for hiding this comment

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

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 goals

Copy link
Member Author

Choose a reason for hiding this comment

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

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 question

Copy link
Member Author

Choose a reason for hiding this comment

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

@ChristianMurphy ping! :)

Copy link
Member

Choose a reason for hiding this comment

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

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.

Copy link
Member Author

Choose a reason for hiding this comment

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

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!

Copy link
Member

Choose a reason for hiding this comment

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

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 🤷

Copy link
Member Author

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

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

* anticipate a follow up question of “Why?” and answer it already
* learn about the [rubber duck debugging method][rubberduckdebugging],
it really helps
* avoid falling for the [XY problem][stackexchange-xy-problem]
* provide sample code:
a markdown code block,
[CodeSandbox][],
[StackBlitz][],
video
Copy link
Member

Choose a reason for hiding this comment

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

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?

Copy link
Member Author

Choose a reason for hiding this comment

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

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


[nlcst]: https://github.com/syntax-tree/nlcst
## License

[hast]: https://github.com/syntax-tree/hast
This document has the following license:
[CC-BY-4.0][creativecommons-by] © [Titus Wormer][wooorm]

[unified]: https://github.com/unifiedjs/unified
[codesandbox]: https://codesandbox.io

[remark]: https://github.com/remarkjs/remark
[creativecommons-by]: https://creativecommons.org/licenses/by/4.0/

[retext]: https://github.com/retextjs/retext
[file-code-of-conduct]: code-of-conduct.md

[rehype]: https://github.com/rehypejs/rehype
[file-contributing]: contributing.md

[mdx]: https://github.com/mdx-js/mdx
[github-search-discussions]: https://github.com/orgs/syntax-tree/discussions

[rubberduck]: https://rubberduckdebugging.com
[github-search-issues]: https://github.com/search?q=user%3Asyntax-tree&type=issues

[xy]: https://meta.stackexchange.com/questions/66377/what-is-the-xy-problem/66378#66378
[rubberduckdebugging]: https://rubberduckdebugging.com

[codesandbox]: https://codesandbox.io
[stackblitz]: https://stackblitz.com

[chat]: https://github.com/syntax-tree/unist/discussions
[stackexchange-xy-problem]: https://meta.stackexchange.com/questions/66377/what-is-the-xy-problem/66378#66378

[contributing]: contributing.md
[wooorm]: https://wooorm.com