Contributing documentation#

This is an overview of documentation resources for Nix, Nixpkgs, and NixOS, with suggestions how you can help to improve them. Documentation contributions should follow the style guide.

Feel free to get in touch with the Nix documentation team if you want to help out.

Important

If you cannot contribute time, consider donating to the NixOS Foundation’s documentation project on Open Collective to fund ongoing maintenance and development of reference documentation and learning materials.

Reference manuals#

The manuals for Nix (source), Nixpkgs (source), and NixOS (source) are purely reference documentation, specifying interfaces and behavior.

They also show example interactions which demonstrate 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

  • picking up documentation-related issues on Nix, Nixpkgs, and NixOS.

  • reviewing documentation-related pull requests on Nix, Nixpkgs, and NixOS.

  • 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

    • clarify language

    • expanding on sections that appear incomplete

    • identifying sections that are not reference documentation and should be moved to nix.dev

nix.dev#

The purpose of nix.dev (source) 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.

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. 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, 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

New articles can be based on videos such as:

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#

The Nix project web site is nixos.org (source).

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.

Communication channels#

Matrix#

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#

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.

External sources#

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.

Wiki#

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 does not maintain the Wiki.

You can still 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 Pills#

Nix Pills is a series of low-level tutorials on building software packages with Nix, showing in detail how Nixpkgs is made from first principles. Work is currently being done to bring the Nix Pills up-to-date with the current state of Nix and current best-practices of Nixpkgs. Furthermore, work is underway to migrate the technical infrastructure of Nix Pills to improve maintainability and make it easier for others to contribute.

You can help by

  • opening issues for any errors or outdated information you find

  • addressing good first issues by opening pull requests

  • Test code examples to ensure correctness and completeness.

  • Add links to reference documentation where needed.

Licensing and attribution#

When opening pull requests with your own contributions, you agree to licensing your work under CC-BY-SA 4.0.

When adding material by third parties, make sure it has a license that permits this. In that case, unambiguously state source, authors, and license in the newly added material. Notify the authors before using their work.

Add the original author as co-author to the first commit of your pull request, which should contain the original document verbatim, so we can track authorship and changes through version history.

Using free licenses other than CC-BY-SA 4.0 is possible for individual documents, and by contributing changes to those documents you agree to license your work accordingly.

Note

If you have written a tutorial or guide related to Nix, please consider licensing it under CC-BY-SA 4.0! This will allow us to feature your work as official documentation if it complements or improves upon existing materials.