3 ms·

> but the connection between those two things is essentially undocumented I often think documentation would be vastly improved if the author was simply answeri

> but the connection between those two things is essentially undocumented I often think documentation would be vastly improved if the author was simply answering the question _what problem did you solve, and how?_, but that seems like it would reveal too much of the dirty details of the design process somehow, so they try to describe the all the neatly encapsulated abstractions and metaphors they've come up with to describe the system (and to encode their own eventual understanding of it) instead. Basically - give us the dirty details and we can make the generalisations ourselves, instead of trying to load the generalised structures into our minds in the most efficient way possible.

tazjin 5y ago
This implies that the author of the documentation is the person that wrote the thing though, which is surprisingly rare in larger projects. I wrote one of the more popular Nix language tutorials[0] and my approach there has been to try and explain everything as straightforwardly as possible and make it work both as a reference and a manual (i.e. you can quickly jump to a section that interests you, or read it from top-to-bottom). One thing that nixpkgs (the Nix package set, which is ~most of the public Nix code) suffers from is reinvention of abstractions (simply due to its age). For example, most programming languages have their own slightly different implementation of a `withPackages` function that gives you a prepared environment with some dependencies. Some of these use open sets, some of them use closed sets, in the latter cases overlaying things into them can get really confusing even for experienced Nix users and so on. In my opinion, the community should slow its focus on making lots of new features and spend time consolidating existing logic and agreeing on some basic abstractions. Maintenance work like that is not always fun though, and especially in unpaid open-source projects it's difficult to keep up the motivation for it. [0]: https://github.com/tazjin/nix-1p https://github.com/tazjin/nix-1p

tazjin 5y ago

This implies that the author of the documentation is the person that wrote the thing though, which is surprisingly rare in larger projects. I wrote one of the more popular Nix language tutorials[0] and my approach there has been to try and explain everything as straightforwardly as possible and make it work both as a reference and a manual (i.e. you can quickly jump to a section that interests you, or read it from top-to-bottom). One thing that nixpkgs (the Nix package set, which is ~most of the public Nix code) suffers from is reinvention of abstractions (simply due to its age). For example, most programming languages have their own slightly different implementation of a `withPackages` function that gives you a prepared environment with some dependencies. Some of these use open sets, some of them use closed sets, in the latter cases overlaying things into them can get really confusing even for experienced Nix users and so on. In my opinion, the community should slow its focus on making lots of new features and spend time consolidating existing logic and agreeing on some basic abstractions. Maintenance work like that is not always fun though, and especially in unpaid open-source projects it's difficult to keep up the motivation for it. [0]: https://github.com/tazjin/nix-1p https://github.com/tazjin/nix-1p