 | Nix Documentation | 435 Members |
| Discussion about documentation improvements around the Nix ecosystem | 92 Servers |
| Nix Documentation | 435 Members |
| Discussion about documentation improvements around the Nix ecosystem | 92 Servers |
| Sender | Message | Time |
|---|---|---|
| 26 Oct 2022 | ||
 Sandro 🐧 | well, it is about what flakes can do because nix just imports some source code that flakes downloaded and turns on some tighter isolation (--pure). | 14:24:53 |
| Sandro 🐧 |
| 14:26:02 |
 joepie91 🏳️🌈 | chreekat: first pass at a better 'headline' description:
thoughts? | 14:48:01 |
 chreekat | In reply to @joepie91:pixie.town I think it's getting there! Some suggestions:
| 14:58:10 |
| chreekat | Even "Flakes make it easier to..." implies the thing that came before, though. :) Newcomers won't know the difference | 15:00:23 |
| chreekat | "Flakes are a mechanism for ..." | 15:00:39 |
| chreekat | Although I do think it's useful to have a comparison to the old way | 15:00:59 |
| chreekat | In reply to @b:chreekat.netIn a fit of unproductivity today I wrote https://twitter.com/chreekat/status/1585236514241654784 for example | 15:02:43 |
| joepie91 🏳️🌈 | chreekat: so on the point of timelessness, I think it's tricky because there are two entirely different audiences that documentation around Flakes needs to appeal to right now; one is the transitory audience which is currently used to other mechanisms and wants to learn why they should care about Flakes, whereas the other have no familiarity with Nix at all and to whom Flakes don't register as anything special. and I feel like right now it's primarily the former audience, and that will eventually erase itself over time, to a point where there's only the latter audience and "Flakes" as a feature ceases to have any meaning, because by then it's just a part of Nix and so people only need to know about the individual concepts that were introduced by Flakes (eg. a "flake"), but those are now just a part of Nix and not of "Flakes" | 15:03:11 |
| joepie91 🏳️🌈 | so documenting "Flakes" as a feature, I think, only really makes sense with the former audience in mind; whereas documenting the features introduced by Flakes makes sense for both audiences, but requires a different approach | 15:04:05 |
| joepie91 🏳️🌈 | if that makes sense | 15:04:33 |
| chreekat | I agree there are different audiences! It makes sense | 15:04:38 |
| chreekat | I guess I fall on the side of just documenting the features, though, with comparisons left for blog posts or appendices. Probably 50% of today's Nix users started using Nix with flakes already present | 15:05:40 |
| chreekat | at least | 15:05:45 |
| joepie91 🏳️🌈 | as for the "guarantees of Nix", that should probably be a link to a more generic explanation of those, plus a reference to specific items from that link - I don't think it makes sense to inline all of the guarantees in the Flakes docs as it's relevant in many other places also | 15:05:58 |
| chreekat | (though many, like me, haven't started using them yet) | 15:06:02 |
| chreekat | Yeah that makes sense, although in terms of writing style, I think it wouldn't hurt to add a small signpost. otoh I'm contradicting myself a bit.. of course Nix guarantees what Nix guarantees ;) | 15:07:42 |
| joepie91 🏳️🌈 | In reply to @b:chreekat.netthis actually makes me a bit uncomfortable, because from the questions/frustrations I'm seeing, Flakes aren't really ready to be recommended for new users yet... | 15:07:42 |
| joepie91 🏳️🌈 | oh yeah, hence the 'reference to item from' thing | 15:08:18 |
| chreekat | I know, it makes me uncomfortable too | 15:08:22 |
| chreekat | Well, back to the point, no harm in dropping my suggestion re: timelessness | 15:09:19 |
| joepie91 🏳️🌈 |
on this point... I don't think it'd be clearer? like, it doesn't really do that? | 15:10:35 |
| joepie91 🏳️🌈 | unless there's something I'm missing | 15:10:43 |
| joepie91 🏳️🌈 | it's specifically the "dealing with different sources" that it makes easier | 15:11:02 |
| joepie91 🏳️🌈 | (and all of the modularity benefits that derive from that, of course) | 15:11:14 |
| chreekat | I guess I just don't know what that means | 15:11:24 |
| chreekat | Like, so far I understand that flake.nix is a Nix file with a particular structure, and a flake is a file tree with a flake.nix. Furthermore, flake.nix can specify dependencies (as other flakes) and <mumble mumble> | 15:13:03 |
| joepie91 🏳️🌈 | so AIUI, the motivation behind flakes is that instead of needing to have all your package definitions in a single repository, and having to do weird possibly stateful hackery (NIX_PATH, import-from-URL, ...) to work around that, there's now a first-class mechanism for establishing dependencies between, for lack of a better term, different "registries" of Nix expressions | 15:13:25 |
| chreekat | so I'm fixated on the dependencies part because that's the only bit I think I understand so far :D | 15:13:27 |
| joepie91 🏳️🌈 | that are possibly maintained by different people | 15:13:42 |