How to contribute to documentation

If you want to help improving Nix documentation, consider the following guidelines developed by the Nix documentation team.

Different audiences require different levels of sophistication, and both readers’ and contributors’ available time and expertise varies widely.

The following diagram shows a pipeline for contributions to learning material and documentation.
Use it to decide where to best put the results of your efforts, depending on how much time you can spend on refining them to get accepted.

Arrows point towards

  • decreasing rate of change
  • increasing public visibility
  • increasing amount of scrutiny.

Communication platforms are distinguished by mode of interaction:

  • append to streams
    • amount of infomation grows without bounds
    • only recent items are relevant
  • change artifacts
    • amount of information is strictly bounded
    • all items should be up to date

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. Feel free to post what you have found valuable on Discourse.

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

  • external sources

    The Internet is full of helpful resources concerning Nix.
    Feel free to share what you have found valuable on Discourse in the Links category.

  • 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
    • writing down what you have learned by updateing or adding a NixOS Wiki article.
  • 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, 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.

    Guidelines for migration:

  • manuals

    The manuals for

    are primarily 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 or Nix issues concerning documentation
    • reviewing Nix pull requests and Nixpkgs and NixOS pull requests concerning documentation
    • making pull requests to correct contents or clarify language
    • expanding on sections that appear incomplete
    • documenting how the manuals are built and organized
    • identifying sections that are not specific enough and should be moved to nix.dev or NixOS Wiki
  • 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.

    You can help by

    New articles can be based on videos such as

    Since writing a guide 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

    The Nix project web site is nixos.org (source).
    Web site 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.

Contributing to this guide

Do you have suggestions how to ease contributing to Nix documentation? Please get in touch!

7 Likes
Hosted by Flying Circus.