diff --git a/source/contributing/documentation/index.md b/source/contributing/documentation/index.md index 4391d7b81..246af46e5 100644 --- a/source/contributing/documentation/index.md +++ b/source/contributing/documentation/index.md @@ -9,41 +9,6 @@ Feel free to get in touch with the [Nix documentation team](https://nixos.org/co 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. ::: -## What you can do to help - -### You want to learn and use Nix? - -This project would not be possible without you. -Try to use it as your primary resource, however incomplete it may appear. - -We ask you to liberally open issues and document all problems and questions that arise. -Please also state your learning goals and the paths you have taken so far. - -Sharing your first-hand experience is invaluable to better guide our efforts, and will immediately help improve these guides for yourself and everyone else. - -### You are a beginner and want to get involved in improving documentation? - -Please go through nix.dev and report any problems you come across in the [issue tracker](https://github.com/NixOS/nix.dev/issues). -Also check to see if there's already an existing issue or pull request that addresses the problem you encountered. - -Another way to help is to help with the [Documentation Survey](https://github.com/NixOS/nix.dev/blob/master/maintainers/documentation-survey.md), which lists other documentation resources as a reference, and can be used to inform new content. - -### You have experience teaching Nix? - -You will probably have observed where learners get stuck most often, and which typical needs and questions they have. -You may have your own written notes for classes, trainings, or presentations. - -Please share your experience and help us inform the structure and detailed contents of the guides. -It would be great if you could contribute examples, wordings, or illustrations that proved helpful to your students. - -### You are a domain expert using Nix? - -If you are proficient in applying Nix to a domain-specific problem, and want to share your expertise on best practices, please check the existing content. -- Does existing material on your subject meet your standards? -- How could we improve it? -- Is there a popular application of Nix' capabilities not yet covered? -- We would be glad to incorporate your insights. - ## Reference manuals The manuals for [Nix](nix-manual) ([source][nix manual src]), [Nixpkgs][Nixpkgs manual] ([source][nixpkgs manual src]), and [NixOS][NixOS manual] ([source][nixos manual src]) are purely reference documentation, specifying interfaces and behavior. @@ -83,35 +48,65 @@ You can help by ## nix.dev The purpose of [nix.dev] ([source][nix.dev src]) 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 +### What you can do to help -- working on [open issues][nix.dev issues] -- reviewing [pull requests][nix.dev prs] by testing new material or features -- adding guides or tutorials following the [proposed outline](https://github.com/NixOS/nix.dev/blob/master/CONTRIBUTING.md#user-content-vision) +#### You want to learn and use Nix? -New articles can be based on videos such as: +This project would not be possible without you. +Try to use it as your primary resource, however incomplete it may appear. + +We ask you to liberally open issues and document all problems and questions that arise. +Please also state your learning goals and the paths you have taken so far. + +Sharing your first-hand experience is invaluable to better guide our efforts, and will immediately help improve these guides for yourself and everyone else. + +#### You are a beginner and want to get involved in improving documentation? -- [The Nix Hour] recordings -- some of the ~100 [NixCon][nixcon yt] recordings -- [Nix video guides] by @jonringer. -- [Summer of Nix 2022 talks] +Please go through nix.dev and report any problems you come across in the [issue tracker](https://github.com/NixOS/nix.dev/issues). +Also check to see if there's already an existing issue or pull request that addresses the problem you encountered. -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. +Another way to help is to help with the [Documentation Survey](https://github.com/NixOS/nix.dev/blob/master/maintainers/documentation-survey.md), which lists other documentation resources as a reference, and can be used to inform new content. + +#### You have experience teaching Nix? + +You will probably have observed where learners get stuck most often, and which typical needs and questions they have. +You may have your own written notes for classes, trainings, or presentations. + +Please share your experience and help us inform the structure and detailed contents of the guides. +It would be great if you could contribute examples, wordings, or illustrations that proved helpful to your students. + +#### You are a domain expert using Nix? + +If you are proficient in applying Nix to a domain-specific problem, and want to share your expertise on best practices, please check the existing content. +- Does existing material on your subject meet your standards? +- How could we improve it? +- Is there a popular application of Nix' capabilities not yet covered? +- We would be glad to incorporate your insights. + +#### You want to write documentation? + +You can help by + +- working on [open issues][nix.dev issues] +- reviewing [pull requests][nix.dev prs] by testing new material or features +- adding guides or tutorials following the [proposed outline](https://github.com/NixOS/nix.dev/issues/572) [nix.dev]: https://nix.dev [nix.dev src]: https://github.com/nixos/nix.dev [nix.dev issues]: https://github.com/nixos/nix.dev/issues [nix.dev prs]: https://github.com/nixos/nix.dev/pulls -[The Nix Hour]: https://www.youtube.com/watch?v=wwV1204mCtE&list=PLyzwHTVJlRc8yjlx4VR4LU5A5O44og9in -[nixcon yt]: https://www.youtube.com/c/NixCon -[Nix video guides]: https://www.youtube.com/user/elitespartan117j27 -[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/user/elitespartan117j27) 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 maintainers, for example by commenting on or opening an issue to make sure it will be worthwhile. ## nixos.org