This guide explains how you can contribute documentation to Nix, Nixpkgs, or NixOS.
List of available documentation¶
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 doing the following:
making pull requests which improves existing documentation, such as:
add links to definitions, commands, options, etc. where only the name is mentioned
correct obvious errors
expanding on sections that appear incomplete
identifying sections that are not reference documentation and should be moved to nix.dev
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
reviewing pull requests by testing new material or features
adding guides or tutorials following the [proposed outline][nix docs outline]
New articles can be based on videos such as:
The Nix Hour recordings
some of the ~100 NixCon recordings
Nix video guides by @jonringer.
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.
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.
List of communication channels¶
Use Matrix for casual communication.
The documentation team frequents the Nix* Documentation room.
Old messages are extremely improbable to be read by anyone.
You can help by posting in the appropriate categories on Discourse what you have found valuable.
Discourse is the central community hub.
This is the place for your questions, suggestions, and discussion.
The documentation team monitors the Documentation 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 article, nix.dev guide or tutorial, or one of the manuals
encouraging and helping people to incorporate their insights in the official documentation
Meetings and Events¶
Check the Discourse community calendar for real-time events.
The documentation team holds regular meetings and posts meeting notes in the Documentation category.
You can help by joining meetings to take notes or clean them up before publishing.
The Internet is full of helpful resources concerning Nix.
You can help by sharing in the Links category on Discourse what you have found valuable.
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 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:
Use welcoming and inclusive language
Show empathy and respect towards other people
Be respectful of different viewpoints and experiences
Give and gracefully accept constructive criticism
Focus on what is best for the community
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.
I would have written a shorter letter, but I did not have the time.
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.
Follow the evidence-based plain language guidelines.
Describe the subject factually.
Use imperative in direct instructions.
Clarity and brevity outweighs emotional appeal.
Do not presuppose a personal relationship with readers.
Address the reader with “you” when necessary.
Clarify identity if you use “we”. Generally, “we” are the Nix community.
Use culturally neutral language:
Idioms can be hard to understand for non-native English speakers.
Don’t try to be funny.
Humor is highly culturally sensitive.
At best, jokes may obfuscate the relevant instructions.
At worst, jokes may offend readers and invalidate our effort to help them learn.
Don’t use references to popular culture.
What you may consider well-known may be entirely obscure and distracting to people from different backgrounds.
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.
Use reference links to keep the plain text readable.
Collect links at the end of each section, which are delimited by headings.