This guide shows how you can contribute documentation to Nix, Nixpkgs, or NixOS.
It is maintained by the [Nix documentation team](https://nixos.org/community/teams/documentation), your first point of contact if you want to help out.
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 doing the following:
- working on [open issues][nix.dev issues]
- reviewing [pull requests][nix.dev prs] by testing new material or features
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.
[Nix video guides]: https://www.youtube.com/user/elitespartan117j27
[Summer of Nix 2022 talks]: https://www.youtube.com/playlist?list=PLt4-_lkyRrOMWyp5G-m_d1wtTcbBaOxZk
### nixos.org
The Nix project web site is [nixos.org] ([source][nixos website src]).
Website contents that concern learning Nix should reference or include material from nix.dev.
The [Nix marketing team] is responsible for the web site, and the documentation team assists with maintaining contents related to onboarding new users.
[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]), by incrementally incorporating its contents into authoritative documentation and curated learning material.
[The Carpentries Code of Conduct]: https://github.com/carpentries/docs.carpentries.org/blob/4691971d9f49544054410334140a4fd391a738da/topic_folders/policies/code-of-conduct.md
### Be truthful
The only thing more confusing than no documentation is misleading documentation.
#### Use and provide evidence
Documentation should enable readers to answer all their questions on their own.
Provide links to other resources, such as the manuals, if it would help guide readers on their learning journey.
It is explicitly encouraged to update or restructure the manuals where appropriate, to improve the overall experience.
Similarly, the other information surrounding documentation should enable contributors to answer most of their questions and correct obvious errors on their own, and only then resort to opening issues.
Errors get more obvious if we can measure execution against intent.
Therefore we ask you to always make explicit the motivation behind your proposed changes.
Add references to any relevant resources in commit messages, if it helps understand the reasoning behind a significant change.
#### Ensure working code samples
Code samples must always be working correctly when run as instructed.
Nix provides us with everything needed to make this happen.
### Be concise
> I would have written a shorter letter, but I did not have the time.
>
> — [Blaise Pascal][Blaise Pascal]
Readers' time and attention is limited.
Take the time to be extraordinarily respectful with their cognitive resources.
The same holds for communication directed to contributors and maintainers: This is a public project, and many people will read what you write. Use this leverage with care.
[GitHub URLs to specific commits]: https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files
[Wikipedia URLs to specific page versions]: https://en.m.wikipedia.org/wiki/Wikipedia:Linking_to_Wikipedia#Permanent_links_to_old_versions_of_pages
[Internet Archive "Save Page Now" for persisting web pages]: https://web.archive.org/save
### Markdown
- Write one sentence per line.
This makes long sentences immediately visible, and makes it easier to manage changes.
The rule is unambiguous and does not require tooling support to be applied easily.
[Here is a discussion of different line wrapping styles.]
- Use [reference links] to keep the plain text readable.
Collect links at the end of each section, which are delimited by headings.
[Here is a discussion of different line wrapping styles.]: https://web.archive.org/web/20220519121408/https://mtsknn.fi/blog/4-1-wrapping-styles-for-markdown-prose-and-code-comments/