Merge 3b5fee627c into 53cbd112d7

source/conf.py

@@ -78,7 +78,7 @@ master_doc = "index"
 
 # General information about the project.
 project = "nix.dev"
-author = "the nix.dev contributors."
+author = "the <a href=\"https://nixos.org/community/teams/documentation\">Nix documentation team</a> and contributors."
 copyright = "2016-" + str(date.today().year) + ", NixOS Foundation"
 
 # The version info for the project you're documenting, acts as replacement for

source/contributing/documentation/index.md

@@ -5,7 +5,7 @@ Documentation contributions should follow the [style guide](./style-guide.md).
 
 Feel free to get in touch with the [Nix documentation team](https://nixos.org/community/teams/documentation) if you want to help out.
 
-:::{attention}
+:::{important}
 If you cannot contribute time, consider [donating to the NixOS Foundation's documentation project on Open Collective](https://opencollective.com/nixos/projects/documentation-project) to fund ongoing maintenance and development of reference documentation and learning materials.
 :::
 

source/contributing/how-to-contribute.md

@@ -6,6 +6,13 @@ Keeping it working and up to date – and improving it continuously – would no
 
 This guide shows how you can contribute to {term}`Nix`, {term}`Nixpkgs` or {term}`NixOS`.
 
+:::{important}
+If you cannot contribute time, consider [donating to the NixOS Foundation on Open Collective](https://opencollective.com/nixos).
+
+Currently the focus is on funding in-person events to share knowledge and grow the community of developers proficient with Nix.
+With enough budget, it would be possible to pay for ongoing maintenance and development of critical infrastructure and code – demanding work that we cannot expect to be done by volunteers indefinitely.
+:::
+
 ## Getting started
 
 Start with asking informed questions, after reading reference documentation and the code relevant to what you care about.
@@ -25,22 +32,17 @@ This is where we need the most help and where it is the easiest to begin.
 Documentation and contribution guides are often incomplete or outdated, much as we would like them to be otherwise.
 We're working on it.
 You can help and improve the situation for everyone by immediately solving problems with the contribution workflow as you encounter them.
-While this may slow you down with addressing your original concern, it will make it a lot easier for anyone to make meaningful contributions in the future, and lead to better code and documentation in the long run.
-
-:::{attention}
-If you cannot contribute time, consider [donating to the NixOS Foundation on Open Collective](https://opencollective.com/nixos).
-
-Currently the focus is on funding in-person events to share knowledge and grow the community of developers proficient with Nix.
-With enough budget, it would be possible to pay for ongoing maintenance and development of critical infrastructure and code – demanding work that we cannot expect to be done by volunteers indefinitely.
-:::
+This may slow you down with addressing your original concern.
+But it will make it a lot easier for anyone to make meaningful contributions in the future.
+And it will lead to better code and documentation in the long run.
 
 ## Report an issue
 
 We can only fix issues that we know of, so please report any issue you encounter.
 
-- Issues with {term}`Nix` (including the [Nix reference manual](https://nixos.org/manual/nix/stable)) are reported at <https://github.com/NixOS/nix/issues>.
+- Report issues with {term}`Nix` (including the [Nix reference manual](https://nixos.org/manual/nix/stable)) at <https://github.com/NixOS/nix/issues>.
 
-- Issues with {term}`Nixpkgs` or {term}`NixOS` (including packages, configuration modules, the [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable), and the [NixOS manual](https://nixos.org/manual/nixos/stable)) are reported at <https://github.com/NixOS/nixpkgs/issues>.
+- Report issues with {term}`Nixpkgs` or {term}`NixOS` (including packages, configuration modules, the [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable), and the [NixOS manual](https://nixos.org/manual/nixos/stable)) at <https://github.com/NixOS/nixpkgs/issues>.
 
 Make sure that there is not already an open issue for your problem.
 Please follow the issue template and fill in all requested information.

source/contributing/how-to-get-help.md

@@ -3,40 +3,54 @@
 If you need assistance with one of your contributions, there are a few places you
 can go for help.
 
-For better efficiency and chances of success, you should try contacting individuals or
-groups with more specific knowledge first:
+## How to find maintainers
+
+For better efficiency and higher chance of success, you should try contacting individuals or groups with more specific knowledge first:
 
 - If your contribution is for a package in Nixpkgs, look for its maintainers in the
   [`maintainers`](https://nixos.org/manual/nixpkgs/stable/#var-meta-maintainers)
   attribute.
-- Check out if any teams are responsible for the relevant subsystem:
+- Check if any teams are responsible for the relevant subsystem:
   - On the [NixOS website](https://nixos.org/community/#governance-teams).
   - In the [list of Nixpkgs maintainer teams](https://github.com/NixOS/nixpkgs/blob/master/maintainers/team-list.nix).
   - In the `CODEOWNERS` files for [Nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/.github/CODEOWNERS) or
     [Nix](https://github.com/NixOS/nix/blob/master/.github/CODEOWNERS).
-- Look at the [git log](https://www.git-scm.com/docs/git-log) for the files you need help
-  with, and take note of the email addresses of people who committed.
+- Check the output of [`git blame`](https://git-scm.com/docs/git-blame) or [`git log`](https://www.git-scm.com/docs/git-log) for the files you need help with.
+  Take note of the email addresses of people who committed relevant code.
 
-Once you've found the people you're looking for, you can contact them via:
+## Which communication channels to use
+
+Once you've found the people you're looking for, you can contact them on one of the following platforms:
 
 - GitHub
 
-  [Mention the GitHub username](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) found in the [`maintainers-list.nix` file][maintainers-list] in issue or pull request descriptions, or comments.
+  All the source code is maintained on GitHub.
+  This is the right place to discuss implementation details.
+
+  In issue comments or pull request descriptions, [mention the GitHub username](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) found in the [`maintainers-list.nix` file][maintainers-list].
 
 - [Discourse](https://discourse.nixos.org)
 
+  Discourse is used for announcements, coordination, and open-ended questions.
+
   Try the GitHub username found in the [`maintainers-list.nix` file][maintainers-list] to mention or directly contact a specific user.
   Note that some people use a different username on Discourse.
 
 - [Matrix]
 
-  Use the Matrix handle found in the [`maintainers-list.nix` file][maintainers-list].
-  If no Matrix handle is present for a specific maintainer, try searching for them using their GitHub username, as most people tend to use the same one across channels.
+  Matrix is used for direct messages and short-lived, timely exchanges.
+
+  To contact a maintainer, use their Matrix handle found in the [`maintainers-list.nix` file][maintainers-list].
+  If no Matrix handle is present for a specific maintainer, try searching for their GitHub username, as most people tend to use the same one across channels.
+
+  Maintainer teams usually have their own public Matrix room.
 
 - Email
 
   Use email addresses found with `git log`.
 
+## Other venues
+
 If you haven't found any specific users or groups that could help you with your
 contribution, you can resort to asking the community at large, using one of the following official
 communication channels:

source/index.md

@@ -10,6 +10,7 @@ myst:
 # Welcome to nix.dev
 
 nix.dev is the home of official documentation for the Nix ecosystem.
+It is maintained by the [Nix documentation team](https://nixos.org/community/teams/documentation).
 
 If you're new here, {ref}`install Nix <install-nix>` and begin your journey with our tutorial series!