From 57af388f1b3d147309735ec7d6bed7b5a9483af4 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 10 Nov 2022 15:05:20 +0100 Subject: [PATCH 1/3] add The Nix Hour recordings to list of transcription tasks --- maintainers/how-to-contribute-to-documentation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/maintainers/how-to-contribute-to-documentation.md b/maintainers/how-to-contribute-to-documentation.md index 4b922e6..bd8638a 100644 --- a/maintainers/how-to-contribute-to-documentation.md +++ b/maintainers/how-to-contribute-to-documentation.md @@ -157,6 +157,7 @@ flowchart - follow the [contribution guide](https://github.com/NixOS/nix.dev/blob/master/CONTRIBUTING.md) New articles can be based on videos such as + - [The Nix Hour](https://www.youtube.com/watch?v=wwV1204mCtE&list=PLyzwHTVJlRc8yjlx4VR4LU5A5O44og9in) recordings - some of the ~100 [NixCon](https://www.youtube.com/c/NixCon) recordings - [Nix video guides](https://www.youtube.com/channel/UC-cY3DcYladGdFQWIKL90SQ) by @jonringer. - [Summer of Nix 2022 talks](https://www.youtube.com/playlist?list=PLt4-_lkyRrOMWyp5G-m_d1wtTcbBaOxZk) From 3142ebdce3c880e3956ec43a64c5eee41541ba4f Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 10 Nov 2022 15:07:38 +0100 Subject: [PATCH 2/3] formatting: fix indentation --- .../how-to-contribute-to-documentation.md | 186 +++++++++--------- 1 file changed, 94 insertions(+), 92 deletions(-) diff --git a/maintainers/how-to-contribute-to-documentation.md b/maintainers/how-to-contribute-to-documentation.md index bd8638a..990b6d9 100644 --- a/maintainers/how-to-contribute-to-documentation.md +++ b/maintainers/how-to-contribute-to-documentation.md @@ -16,12 +16,14 @@ Arrows point towards Communication platforms are distinguished by mode of interaction: Streams can be appended to: - - The amount of infomation in them grows without bounds. - - Only recent items are relevant. + +- The amount of infomation in them grows without bounds. +- Only recent items are relevant. Artifacts can be changed: - - The amount of information in them is strictly bounded. - - All items should be up to date. + +- The amount of information in them is strictly bounded. +- All items should be up to date. ```mermaid flowchart @@ -53,124 +55,124 @@ flowchart - Matrix - Use Matrix for casual communication. - - The documentation team frequents the [Nix* Documentation](https://app.element.io/#/room/#docs:nixos.org) room. - - Old messages are extremely improbable to be read by anyone. + Use Matrix for casual communication. + + The documentation team frequents the [Nix\* Documentation](https://app.element.io/#/room/#docs:nixos.org) room. + + Old messages are extremely improbable to be read by anyone. - You can help by posting in the appropriate categories on [Discourse](https://discourse.nixos.org/) what you have found valuable. + You can help by posting in the appropriate categories on [Discourse](https://discourse.nixos.org/) what you have found valuable. - meetings and events - Check the [Discourse community calendar](https://discourse.nixos.org/t/community-calendar/18589) for real-time events. - - The documentation team holds regular meetings and posts meeting notes in the [Documentation](https://discourse.nixos.org/c/dev/documentation/25) category. - - You can help by joining meetings to take notes or clean them up before publishing. + Check the [Discourse community calendar](https://discourse.nixos.org/t/community-calendar/18589) for real-time events. + + The documentation team holds regular meetings and posts meeting notes in the [Documentation](https://discourse.nixos.org/c/dev/documentation/25) category. + + You can help by joining meetings to take notes or clean them up before publishing. - external sources - The Internet is full of helpful resources concerning Nix. + The Internet is full of helpful resources concerning Nix. - You can help by sharing in the [Links](https://discourse.nixos.org/c/links/12) category on Discourse what you have found valuable. + You can help by sharing in the [Links](https://discourse.nixos.org/c/links/12) category on Discourse what you have found valuable. - Discourse - [Discourse](https://discourse.nixos.org/) is the central community hub. - This is the place for your questions, suggestions, and discussion. - - The documentation team monitors the [Documentation](https://discourse.nixos.org/c/dev/documentation/25) category. - - Old threads and especially posts in long threads are improbable to be read by many people. - - You can help by - - - asking informed questions, showing what you have done so far - - answering other people's questions - - writing down what you have learned by updating or adding a [NixOS Wiki](https://nixos.wiki/) article, nix.dev guide or tutorial, or one of the manuals - - encouraging and helping people to incorporate their insights in the official documentation + [Discourse](https://discourse.nixos.org/) is the central community hub. + This is the place for your questions, suggestions, and discussion. + + The documentation team monitors the [Documentation](https://discourse.nixos.org/c/dev/documentation/25) category. + + Old threads and especially posts in long threads are improbable to be read by many people. + + You can help by + + - asking informed questions, showing what you have done so far + - answering other people's questions + - writing down what you have learned by updating or adding a [NixOS Wiki](https://nixos.wiki/) article, nix.dev guide or tutorial, or one of the manuals + - encouraging and helping people to incorporate their insights in the official documentation - Wiki - [NixOS Wiki](https://nixos.wiki/) is a collection of interlinked guides to solve common problems which are otherwise not well-documented. - It is collectively edited by the community, covers a broad range of topics. - It is only loosely organized, and does not impose quality standards. - Its purpose is to quickly and conveniently collect insights and make them readily available for everyone. + [NixOS Wiki](https://nixos.wiki/) is a collection of interlinked guides to solve common problems which are otherwise not well-documented. + It is collectively edited by the community, covers a broad range of topics. + It is only loosely organized, and does not impose quality standards. + Its purpose is to quickly and conveniently collect insights and make them readily available for everyone. - We recommend to use it as a dumping ground for more obscure Nix knowledge, and strive to make it *smaller* over time (see [NixCon 2015: Make Nix friendlier for Beginners](https://media.ccc.de/v/nixcon2015-3-MakeNixfriendlierforBeginners#video&t=1365)), by incrementally incorporating its contents into authoritative documentation and curated learning material. + We recommend to use it as a dumping ground for more obscure Nix knowledge, and strive to make it *smaller* over time (see [NixCon 2015: Make Nix friendlier for Beginners](https://media.ccc.de/v/nixcon2015-3-MakeNixfriendlierforBeginners#video&t=1365)), by incrementally incorporating its contents into authoritative documentation and curated learning material. - The documentation team monitors changes to maintain an overview of topics of interest and prevent vandalism. - - You can help with - - - improving discoverability by adding categorization and relevant links - - clarifying articles and correcting errors - - removing redundant information that is already present in curated sources - - migrating information to other resources. - - Where to migrate what: - - - Nix interaction: [Nix manual](https://nixos.org/manual/nix/stable/) - - Language-specific build instructions: [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/) - - Package, service, or hardware configuration: [NixOS manual](https://nixos.org/manual/nixos/stable/) - - Overviews, tutorials, guides, and best practices: [nix.dev](https://nix.dev/) + The documentation team monitors changes to maintain an overview of topics of interest and prevent vandalism. + + You can help with + + - improving discoverability by adding categorization and relevant links + - clarifying articles and correcting errors + - removing redundant information that is already present in curated sources + - migrating information to other resources. + + Where to migrate what: + + - Nix interaction: [Nix manual](https://nixos.org/manual/nix/stable/) + - Language-specific build instructions: [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/) + - Package, service, or hardware configuration: [NixOS manual](https://nixos.org/manual/nixos/stable/) + - Overviews, tutorials, guides, and best practices: [nix.dev](https://nix.dev/) - manuals - The manuals for + The manuals for + + - [Nix](https://nixos.org/manual/nix/stable/) ([source](https://github.com/NixOS/nix/tree/master/doc/manual)) + - [Nixpkgs](https://nixos.org/manual/nixpkgs/stable/) ([source](https://github.com/NixOS/nixpkgs/tree/master/doc)) + - [NixOS](https://nixos.org/manual/nixos/stable/) ([source](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)) + + are purely reference documentation, specifying interfaces and behavior. + They also show example interactions to show how to use its components, and explain mechanisms where necessary. + + The documentation team watches all pull requests to the manuals and assists contributors to get their changes merged. + + You can help by - - [Nix](https://nixos.org/manual/nix/stable/) ([source](https://github.com/NixOS/nix/tree/master/doc/manual)) - - [Nixpkgs](https://nixos.org/manual/nixpkgs/stable/) ([source](https://github.com/NixOS/nixpkgs/tree/master/doc)) - - [NixOS](https://nixos.org/manual/nixos/stable/) ([source](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)) - - are purely reference documentation, specifying interfaces and behavior. - They also show example interactions to show how to use its components, and explain mechanisms where necessary. - - The documentation team watches all pull requests to the manuals and assists contributors to get their changes merged. - - You can help by - - - working on [Nixpkgs and NixOS issues](https://github.com/NixOS/nixpkgs/issues?q=is%3Aopen+is%3Aissue+label%3A%229.needs%3A+documentation%22) or [Nix issues](https://github.com/NixOS/nix/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation) concerning documentation - - reviewing [Nix pull requests](https://github.com/NixOS/nix/pulls?q=is%3Aopen+is%3Apr+label%3Adocumentation) and [Nixpkgs and NixOS pull requests](https://github.com/NixOS/nixpkgs/pulls?q=is%3Aopen+is%3Apr+label%3A%228.has%3A+documentation%22) concerning documentation - - making pull requests to - - add links to definitions, commands, options, etc. where only the name is mentioned - - correct obvious errors - - clarify language - - expanding on sections that appear incomplete - - documenting how the manuals are organized and built - - identifying sections that are not reference documentation and should be moved to nix.dev + - working on [Nixpkgs and NixOS issues](https://github.com/NixOS/nixpkgs/issues?q=is%3Aopen+is%3Aissue+label%3A%229.needs%3A+documentation%22) or [Nix issues](https://github.com/NixOS/nix/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation) concerning documentation + - reviewing [Nix pull requests](https://github.com/NixOS/nix/pulls?q=is%3Aopen+is%3Apr+label%3Adocumentation) and [Nixpkgs and NixOS pull requests](https://github.com/NixOS/nixpkgs/pulls?q=is%3Aopen+is%3Apr+label%3A%228.has%3A+documentation%22) concerning documentation + - making pull requests to + - add links to definitions, commands, options, etc. where only the name is mentioned + - correct obvious errors + - clarify language + - expanding on sections that appear incomplete + - documenting how the manuals are organized and built + - identifying sections that are not reference documentation and should be moved to nix.dev - nix.dev - The purpose of [nix.dev](https://nix.dev/) ([source](https://github.com/nix-dot-dev/nix.dev)) is to guide newcomers by teaching essential Nix knowledge, show best practices, and help orient users in the Nix ecosystem. - It goes into breadth, not depth. - - The documentation team maintains nix.dev as editors. - - You can help by - - - working on [open issues](https://github.com/nix-dot-dev/nix.dev/issues) - - reviewing [pull requests](https://github.com/nix-dot-dev/nix.dev/pulls) by testing new material or features - - adding guides or tutorials following the [proposed outline](https://github.com/nix-dot-dev/nix.dev/pull/265) - - follow the [contribution guide](https://github.com/NixOS/nix.dev/blob/master/CONTRIBUTING.md) + The purpose of [nix.dev](https://nix.dev/) ([source](https://github.com/nix-dot-dev/nix.dev)) is to guide newcomers by teaching essential Nix knowledge, show best practices, and help orient users in the Nix ecosystem. + It goes into breadth, not depth. + + The documentation team maintains nix.dev as editors. + + You can help by + + - working on [open issues](https://github.com/nix-dot-dev/nix.dev/issues) + - reviewing [pull requests](https://github.com/nix-dot-dev/nix.dev/pulls) by testing new material or features + - adding guides or tutorials following the [proposed outline](https://github.com/nix-dot-dev/nix.dev/pull/265) + - follow the [contribution guide](https://github.com/NixOS/nix.dev/blob/master/CONTRIBUTING.md) - New articles can be based on videos such as - - [The Nix Hour](https://www.youtube.com/watch?v=wwV1204mCtE&list=PLyzwHTVJlRc8yjlx4VR4LU5A5O44og9in) recordings - - some of the ~100 [NixCon](https://www.youtube.com/c/NixCon) recordings - - [Nix video guides](https://www.youtube.com/channel/UC-cY3DcYladGdFQWIKL90SQ) by @jonringer. - - [Summer of Nix 2022 talks](https://www.youtube.com/playlist?list=PLt4-_lkyRrOMWyp5G-m_d1wtTcbBaOxZk) + New articles can be based on videos such as + - [The Nix Hour](https://www.youtube.com/watch?v=wwV1204mCtE&list=PLyzwHTVJlRc8yjlx4VR4LU5A5O44og9in) recordings + - some of the ~100 [NixCon](https://www.youtube.com/c/NixCon) recordings + - [Nix video guides](https://www.youtube.com/channel/UC-cY3DcYladGdFQWIKL90SQ) by @jonringer. + - [Summer of Nix 2022 talks](https://www.youtube.com/playlist?list=PLt4-_lkyRrOMWyp5G-m_d1wtTcbBaOxZk) - Since writing a guide or tutorial is a lot of work, please make sure to coordinate with nix.dev maintainers, for example by commenting on or opening an issue to make sure it will be worthwhile. + Since writing a guide or tutorial is a lot of work, please make sure to coordinate with nix.dev maintainers, for example by commenting on or opening an issue to make sure it will be worthwhile. - [nixos.org](http://nixos.org/) - The Nix project web site is [nixos.org](https://nixos.org/) ([source](https://github.com/NixOS/nixos-homepage)). - Web site contents that concern learning Nix should reference or include material from nix.dev. - - The [Nix marketing team](https://nixos.org/community/teams/marketing.html) is responsible for the web site, and the documentation team assists with maintaining contents related to onboarding new users. + The Nix project web site is [nixos.org](https://nixos.org/) ([source](https://github.com/NixOS/nixos-homepage)). + Web site contents that concern learning Nix should reference or include material from nix.dev. + + The [Nix marketing team](https://nixos.org/community/teams/marketing.html) is responsible for the web site, and the documentation team assists with maintaining contents related to onboarding new users. ## Contributing to this guide From 041e2dd9de1f6d27e3045203d60ed1bdb61c14e1 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 10 Nov 2022 16:55:42 +0100 Subject: [PATCH 3/3] Update maintainers/how-to-contribute-to-documentation.md Co-authored-by: Silvan Mosberger --- maintainers/how-to-contribute-to-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/maintainers/how-to-contribute-to-documentation.md b/maintainers/how-to-contribute-to-documentation.md index 990b6d9..7cb1b7b 100644 --- a/maintainers/how-to-contribute-to-documentation.md +++ b/maintainers/how-to-contribute-to-documentation.md @@ -159,7 +159,7 @@ flowchart - follow the [contribution guide](https://github.com/NixOS/nix.dev/blob/master/CONTRIBUTING.md) New articles can be based on videos such as - - [The Nix Hour](https://www.youtube.com/watch?v=wwV1204mCtE&list=PLyzwHTVJlRc8yjlx4VR4LU5A5O44og9in) recordings + - [The Nix Hour](https://www.youtube.com/playlist?list=PLyzwHTVJlRc8yjlx4VR4LU5A5O44og9in) recordings - some of the ~100 [NixCon](https://www.youtube.com/c/NixCon) recordings - [Nix video guides](https://www.youtube.com/channel/UC-cY3DcYladGdFQWIKL90SQ) by @jonringer. - [Summer of Nix 2022 talks](https://www.youtube.com/playlist?list=PLt4-_lkyRrOMWyp5G-m_d1wtTcbBaOxZk)