!avYyleMexqjFHoqrME:nixos.org

Nix Documentation

418 Members
Discussion about documentation improvements around the Nix ecosystem86 Servers

You have reached the beginning of time (for this room).


SenderMessageTime
20 Nov 2023
@bzzm3r:matrix.org@bzzm3r:matrix.org
In reply to @proofconstruction:matrix.org

The goal is not to have users for the sake of having contribution. The goal is to allow newcomers to learn this tool, so that they too may improve their life through its use.

The trouble here is that non-contributing users (I was one for my first ~6 years using Nix!) are usually not also non- consuming, in the sense of requiring additional resources from teams that already don't have them. Hence the docs effort: well-designed (in particular, narratively-consistent) documentation can be a tremendous force multiplier for teaching, but the Nix ecosystem broadly does not have well-designed docs; famously so! We (again now speaking for others) do in fact want to improve lives by getting more people into effective Nix use, but this is in tension with Nix not actually being a very good tool: its edges are very sharp, and many cut themselves and wind up here looking for aid. That Nix works at all is very nearly a miracle. A chainsaw is useful too, but I don't want to leave one lying around for others to hurt themselves or others with, and right now the hard decision for many of us is between building a sheath for the saw and writing an instruction manual for it. Neither of these are reasonable approaches to the problem of new people running into trouble after picking up the cool saw.

I very much agree with you on this too. 100%.

I think what is special about Nix currently isn't its present day manifestation, but rather the fact that it exists at all, and even in this "sharp-edged" (broken) form, it is a proof of concept of how things could be, if we didn't take an ad hoc, cowboy attitude to everything.

(So it always surprises me that Nix-lang has the shape it does, especially given the intellectual culture it is a product of....)

When you mentioned this, I think I realized an implicit assumption I had made (and I am not sure why I made this, in hindsight!): that flakes/experimental stuff was about taking steps towards improving in Nix as a tool. I am now beginning to realize that they might actually be exactly more cowboy stuff on top of a foundation of cowboy stuff (i.e. no formal, written specification...sigh)

So yeah, overall, I do think we are in strong alignment.

16:56:03
@bzzm3r:matrix.org@bzzm3r:matrix.org Does the "search button" on nix.dev work for you all too? (It currently does not for me (NixOS + Firefox + Privacy Badger + uBlockOrigin + Decentraleyes) 17:26:57
@bzzm3r:matrix.org@bzzm3r:matrix.org also, a lot of the "good first issues" deal with Sphinx issues...would it be too idealistic (definitely not a "good first issue" at the very least) if we just ported nix.dev to something a bit nicer (e.g. Svelte + TypeScript would be nice) 17:28:45
@bzzm3r:matrix.org@bzzm3r:matrix.orgbut I doubt a docs framework exists for that, so yeah, not sure.17:29:17
@infinisil:matrix.orginfinisilSearch works for me in NixOS + Firefox + uBlockOrigin :)17:38:32
@infinisil:matrix.orginfinisil * bzm3r: Search works for me in NixOS + Firefox + uBlockOrigin :) 17:38:42
@nbp:mozilla.orgnbpworks for me with NixOS, Firefox & Privacy badger.17:39:42
@infinisil:matrix.orginfinisil henrik-ch: Did you perhaps already complete a walk through the tutorial? 17:40:11
@nbp:mozilla.orgnbp * works for me with NixOS, Firefox & Privacy badger. (api.github.com is orange when clicking the privacy badger icon)17:40:12
@brainrape:ggpeti.com@brainrape:ggpeti.com changed their display name from brainrake to brainrake (Old).20:18:00
@i97henka:matrix.orghenrik-ch
In reply to @infinisil:matrix.org
henrik-ch: Did you perhaps already complete a walk through the tutorial?
Review posted, it's slightly funny as you have revised slightly since I started the review, but hopefully still something usable. I will check with you tomorrow to see if it's a good point to rereview.
21:57:22
@i97henka:matrix.orghenrik-ch
In reply to @infinisil:matrix.org
henrik-ch: Did you perhaps already complete a walk through the tutorial?
* Review posted, it's slightly funny as you have revised some parts since I started the review, but hopefully still something usable. I will check with you tomorrow to see if it's a good point to rereview.
21:58:04
@infinisil:matrix.orginfinisil henrik-ch: Awesome thanks! No worries, I only appended, I didn't change anything existing :) 21:58:37
@i97henka:matrix.orghenrik-chBy the way, it took me about 40 minutes from start to finish 😆 but that probably says more about my nix skills, and I preferred writing off the examples rather than copy the code from nix.dev for increased learning.22:03:46
@infinisil:matrix.orginfinisil henrik-ch: Ah nice, I think that makes this a pretty good size then! Though I also added a bunch of content afterwards :P 22:07:29
@infinisil:matrix.orginfinisilI will remove some sections though after Valentin's feedback22:07:59
21 Nov 2023
@infinisil:matrix.orginfinisilUpdated https://github.com/NixOS/nix.dev/pull/802, looking pretty good now imo :)02:40:41
@infinisil:matrix.orginfinisil * Updated https://github.com/NixOS/nix.dev/pull/802 and marked as ready for review, looking pretty good now imo :)02:40:52
@brainrape:ggpeti.com@brainrape:ggpeti.com left the room.15:27:59
@niksnut:matrix.orgEelco changed their display name from niksnut to Eelco.16:37:09
@infinisil:matrix.orginfinisil fricklerhandwerk: Unless the github deployments thing is necessary for netlify (I don't think it is?), please turn it off (which needs repo admin permissions afaik), it's spamming events for every PR update: https://github.com/NixOS/nix.dev/pull/802 18:26:02
@asymmetric:matrix.dapp.org.ukasymmetric
In reply to @infinisil:matrix.org
fricklerhandwerk: Unless the github deployments thing is necessary for netlify (I don't think it is?), please turn it off (which needs repo admin permissions afaik), it's spamming events for every PR update: https://github.com/NixOS/nix.dev/pull/802
i think it comes from here: https://github.com/NixOS/nix.dev/blob/master/.github/workflows/build-and-deploy.yml
18:38:55
@asymmetric:matrix.dapp.org.ukasymmetric the action has an enable-github-deployment option which defaults to true. we could make it dependent on whether the push is to master instead 18:39:46
@asymmetric:matrix.dapp.org.ukasymmetric * the netlify action has an enable-github-deployment option which defaults to true. we could make it dependent on whether the push is to master instead 18:40:01
@infinisil:matrix.orginfinisil asymmetric: Ah I see, but what's the point of these github deployments anyways? The comment it posts in the PR always contains an up-to-date link to the netlify deployment 18:41:22
@infinisil:matrix.orginfinisil * asymmetric: Ah I see, but what's the point of these github deployments anyways? The comment it posts in the PR always contains an up-to-date link to the netlify deployment: https://github.com/NixOS/nix.dev/pull/802#issuecomment-1817733137 18:41:35
@asymmetric:matrix.dapp.org.ukasymmetric don't think there's any special utility tbh.. other than getting a view of all deployments, and a summary in the project's sidebar 18:43:59
@infinisil:matrix.orginfinisil asymmetric: https://github.com/NixOS/nix.dev/pull/803 18:54:03

Show newer messages


Back to Room ListRoom Version: 6