1. 27
  1. 8

    Really good ciriticsms, I agree with them all. One mitigating aspect of documentation is that Nix configuration is code so you can search on GitHub and hopefully find an example of whatever you want to achieve.

    1. 8

      I disagree a bit with the last one. Nix has some escape hatches, like FHS user environments.

      The major pain point is documentation. The post is totally right about that. Nix is trying to address it with a documentation team funded by some sponsors:


      I think Nix should try to document the basics much better. IMHO, the basic use cases are simple to learn. Arguably, it’s one of the easiest distros to use if you have very basic needs. And it’s very forgiving. However. it’s getting a reputation for exactly the opposite.

      In this regard, there is https://snowflakeos.org, built on top of Nix, which is quite interesting.

      1. 9

        afaik the funding by Tweag has ended and there is no replacement. A team still seems to be meeting though, recorded here https://discourse.nixos.org/c/dev/documentation/25

        Flakes being experimental is a huge problem for the entire nix/nixpkgs ecosystem, including documentation. Official docs will likely avoid flakes as much as possible, but they are a huge improvement in many areas and reduce some of the major pain points users run in to (eg channels). Flakes have problems, but solving the most important ones and stabilizing the schema should be the top priority of nix.

        1. 4

          afaik the funding by Tweag has ended and there is no replacement.

          According to [0], funding is now provided by https://determinate.systems


      2. 3

        Aside: I hope we get a meta code search tool. I don’t want to rely on GitHub as the only search but the only other search engines aren’t so great at searching just code repositories. Here’s to hoping this was one of SearchHut’s goals.

        1. 2

          The author’s “must search GitHub repo” argument reads like https://search.nixos.org isn’t as know as it should be.

          1. 5

            That tells you something about available options and packages, but close to nothing about “how a service or an option works” [highlight by me]

            1. 3

              I use https://search.nixos.org/ frequently - but this doesn’t help if I don’t already have some idea of what an option does, or if the option is doing something I don’t expect based on its name or documentation (which isn’t always clear anyway), or if I’m trying to use the nix command line tools to do something, or trying to import or create a custom module because the standard nixos-provided modules don’t solve my problem.

          2. 7

            About the authors last point: With the recently released 1.4 Guix got an escape hatch into FHS-land:

            Another guix shell innovation is optional emulation of the filesystem hierarchy standard (FHS). The FHS specifies locations for different file categories—/bin for essential command binaries, /lib for libraries, and so on. Guix with its store does not adhere to the FHS, which prevents users from running programs that assume FHS adherence. The new –emulate-fhs (or -F) flag of guix shell, combined with –container (-C), instructs it to create a container environment that follows the FHS.


            1. 3

              NixOS had pkgs.buildFHSUserEnv for at least a few years. Not sure if the author is aware of it.

              1. 2

                The article mentions it!

                And, to be clear, by « pack it into NixOS », I mean writing a derivation for the package, whether it uses buildFHSEnv or not.

                1. 1

                  Oh sorry, I must have missed that while skimming.

                  Great article in gernal, thanks!