Refactor contributing.md

Author: wooorm

contributing.md

@@ -1,107 +1,123 @@
 # Contributing
 
-> 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 interested in contributing!
 Take a moment to read the following guidelines.
-And thanks for contributing to **unified**!
-👏👌✨
-
-If you’re raising an issue, please understand that people involved with this
-project often do so for fun, next to their day job; you are not entitled to
-free customer service.
+Thanks for contributing!
 
 ## Contents
 
+* [Expectations](#expectations)
 * [Ecosystem](#ecosystem)
+* [Support](#support)
 * [Contributions](#contributions)
   * [Financial support](#financial-support)
   * [Improve documentation](#improve-documentation)
   * [Improve issues](#improve-issues)
   * [Give feedback on issues](#give-feedback-on-issues)
   * [Write code](#write-code)
-* [Support](#support)
 * [Submitting an issue](#submitting-an-issue)
 * [Submitting a pull request](#submitting-a-pull-request)
 * [Resources](#resources)
 * [License](#license)
 
+## Expectations
+
+This community has a [code of conduct][file-code-of-conduct].
+You must follow it when interacting with the community.
+
+Be respectful and considerate when asking for things.
+You are not entitled to free customer service.
+
+Be friendly!
+Be excellent to each other.
+
 ## Ecosystem
 
-The collective ([unified][]) consists of several organizations and separate
-projects: most of them are tiny, and many of them have a utility
-([`mdast-util-to-hast`][mdast-util-to-hast]), a plugin
-([`remark-rehype`][remark-rehype]), and relate to an ecosystem
-([`remark`][remark]) and a syntax tree ([mdast][]).
-Try and pick the right place to contribute to so we can help you faster.
+Pick the right place to contribute.
+The collective ([unified][github-unified]) is hundreds of projects in several
+organizations.
+Often there is
+a utility (such as [`mdast-util-to-hast`][github-mdast-util-to-hast]),
+a plugin ([`remark-rehype`][github-remark-rehype]),
+relating to a syntax tree ([mdast][github-mdast])
+and an ecosystem ([`remark`][github-remark]).
+If you are not sure where to contribute,
+you can first ask a question.
+
+## Support
+
+See [`support.md`][file-support] on how to get help.
 
 ## Contributions
 
-There’s several ways to contribute, not just by writing code.
+There are several ways to contribute.
 
 ### Financial support
 
-It’s possible to support us financially by becoming a backer or sponsor through
-[Open Collective][collective].
-With this support, we can pay for project leadership, finance non-coding work,
-or to do fun things for the community like getting stickers for contributors.
-You’ll be helping unified’s maintainers manage and improve existing projects,
-and additionally support our work to develop new and exciting projects, such
-as [micromark][].
+Support our efforts financially.
+Sponsor us on [GitHub][github-sponsors],
+[`thanks.dev`][thanks],
+or [OpenCollective][].
 
 ### Improve documentation
 
-As a user of this project you’re perfect for helping us improve our docs.
-Typo corrections, error fixes, better explanations, new examples, etcetera.
-Anything!
+Fix that typo.
+As a user you are perfect for helping us improve the docs.
+Better explanations,
+new examples,
+etcetera.
 
 ### Improve issues
 
-Some issues lack information, aren’t reproducible, or are just incorrect.
-Help make them easier to resolve.
+Help make issues easier to resolve.
+Some issues lack information,
+are not reproducible,
+or are just incorrect.
 
 ### Give feedback on issues
 
-We’re always looking for more opinions on discussions in the issue tracker.
+Share your perspective.
+We are often looking for more opinions,
+insights,
+and use cases.
 
 ### Write code
 
-Code contributions are very welcome.
-It’s often good to first create an issue to report a bug or suggest a new
-feature before creating a pull request to prevent you from doing unnecessary
-work.
-
-## Support
-
-See [`support.md`][support] on how to get help.
+Contribute a test,
+patch a bug,
+add a feature.
+It’s often good to first create a discussion or an issue before a pull request.
+Perhaps there’s a reason things are the way they are.
+Or there’s an alternative solution.
 
 ## Submitting an issue
 
-* The issue tracker is for issues.
-  See [`support.md`][support] on how to get help.
-* Search the issue tracker (including closed issues) before opening a new
-  issue
-* Ensure you’re using the latest version of projects
-* Use a clear and descriptive title
-* Include as much information as possible: steps to reproduce the issue,
-  error message, version, operating system, etcetera
-* The more time you put into an issue, the more we will
-* The best issue report is a [failing test][unit-test] proving it
+* see [`support.md`][file-support] for help;
+  the issue tracker is for issues
+* search [discussions][github-search-discussions] and
+  [issues][github-search-issues] before opening something,
+  include links to what you find
+* contribute a failing test if you can
+* use the latest version of projects
+* use a clear and descriptive title
+* include as much information as possible
+* be friendly!
+* the more time you put into an issue,
+  the easier it is to help you
 
 ## Submitting a pull request
 
-* Non-trivial changes are often best discussed in an issue first, to prevent
-  you from doing unnecessary work
-* For ambitious tasks, you should try to get your work in front of the
-  community for feedback as soon as possible
-* New features should be accompanied with tests and documentation
-* Don’t include unrelated changes
-* Lint and test before submitting code by running `$ npm test`
-* Write a convincing description of why we should land your pull request:
+* non-trivial things are often best discussed first,
+  to prevent you from doing unnecessary work
+* for ambitious tasks,
+  try to get your work in front of the community for feedback as soon as
+  possible
+* do one thing and do it well,
+  do not include unrelated changes
+* include tests and documentation
+* run `npm test` to make sure everything’s still fine
+* write a convincing description of why we should land your pull request:
   it’s your job to convince us
 
 ## Resources
@@ -113,30 +129,33 @@ See [`support.md`][support] on how to get help.
 
 ## License
 
-[CC-BY-4.0][license] © [Titus Wormer][author]
+This document has the following license:
+[CC-BY-4.0][creativecommons-by] © [Titus Wormer][wooorm]
+
+[creativecommons-by]: https://creativecommons.org/licenses/by/4.0/
 
-<!-- Definitions -->
+[file-code-of-conduct]: code-of-conduct.md
 
-[license]: https://creativecommons.org/licenses/by/4.0/
+[file-support]: support.md
 
-[author]: https://wooorm.com
+[github-mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast
 
-[coc]: https://github.com/unifiedjs/.github/blob/main/code-of-conduct.md
+[github-mdast]: https://github.com/syntax-tree/mdast
 
-[mdast]: https://github.com/syntax-tree/mdast
+[github-remark-rehype]: https://github.com/remarkjs/remark-rehype
 
-[unified]: https://github.com/unifiedjs/unified
+[github-remark]: https://github.com/remarkjs/remark
 
-[remark]: https://github.com/remarkjs/remark
+[github-unified]: https://github.com/unifiedjs/unified
 
-[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast
+[github-search-discussions]: https://github.com/orgs/unifiedjs/discussions
 
-[remark-rehype]: https://github.com/remarkjs/remark-rehype
+[github-search-issues]: https://github.com/search?q=user%3Aunifiedjs&type=issues
 
-[unit-test]: https://twitter.com/sindresorhus/status/579306280495357953
+[github-sponsors]: https://github.com/sponsors/unifiedjs
 
-[collective]: https://opencollective.com/unified
+[opencollective]: https://opencollective.com/unified
 
-[micromark]: https://github.com/micromark/micromark
+[thanks]: https://thanks.dev
 
-[support]: support.md
+[wooorm]: https://wooorm.com