In reply to @infinisil:matrix.org

bzm3r: Also some unorganized points:

• Instead of diverting our attention to the Flakes discussion again, I'd much rather just have reviews for the actual content of https://github.com/NixOS/nix.dev/pull/802 :)
• Personally, I think Flakes are really poorly designed, and if they get marked as stable as is, I might just fork Nix or leave the community
• Nix is stable when the Nix team calls it stable. In practice this means being able to rely on it for decades to come

Thanks infinisil! I'm still glad that you wrote your tutorial, and that I reviewed it. Also, I'll re-iterate what I wrote in the my post-review comment on GitHub:

Thank you for this! I love reading new tutorials. I have a couple of suggestions, but I'm not really sure what the nix.dev policy is around flakes/"experimental commands", so I might be off-base.

I do wish you had answered my question on GitHub with what you wrote here (then I wouldn't have been confused enough to write what I did). In particular:

Personally, I think Flakes are really poorly designed, and if they get marked as stable as is, I might just fork Nix or leave the community

That's really good to know up-front, because that makes a lot more sense to me around why flakes aren't mentioned in the tutorial, than the rest of the things you told me! (Particularly around the "stabilization" of flakes being the concern of the docs team.)

Nix is stable when the Nix team calls it stable. In practice this means being able to rely on it for decades to come

Fair enough. Again, this is much clearer to me as an answer than "Nix stable is what we're focusing on because flakes are unstable". Like, that suggests that stability is somehow a goal that has to be reached before documentation is meaningful, while what you've written here provides a different picture.

In reply to @proofconstruction:matrix.org

Supposing this is sincere, some answers and responses to the above, in no particular order, with the usual caveats that this is my opinion/perspective and I don’t speak for others, and also that I am both tired (from work unrelated to nix) and frustrated (from the same) so my tone here is less pleasant than I’d normally want to put in public channels:

• pursuing some vague notion of “productivity” for its own sake doesn’t help anyone, and is typically harmful.
• you are free to contribute to the unofficial wiki as you like
• lifting useful content from the wiki for import into the official docs is a project some of us are interested in taking on at some point, but the team is usually only 3 or 4 part time and inconsistently-available contributors in any given week, with most of these volunteering. Resource constraints are severe.
• Onboarding new users has been a goal by both this team and the broader project/ecosystem, but is considered by some (myself among them)to be an anti-goal: users do not necessarily contribute, which is what the project (not just docs, everything) actually needs to flourish.
• you are welcome to “grab a shovel”, as some of us say, and help with the documentation effort (or even better, the flakes stabilization/detangling effort). Meeting times are available on the calendar. Join us!
• I say “detangling” above because flakes are so convoluted as to be difficult to document, and not for lack of trying; see any number of blog posts by various people on this topic, and the fact that we are still having this discussion
• everything is political and many decisions are absolutely made based on aesthetic sensibilities. It is a fact that many involved in this work just don’t like the miserable little pile of features we call “flakes”today, and believe those pieces should be included in nix in a different form. Much digital ink has been spilled on this already

First off, I don't think you know what is going on in my life either. I didn't advertise my challenges, nor did I use it as an excuse to be cruel. So to hear things like "supposing this is sincere..." and then to be told things like:

• pursuing some vague notion of “productivity” for its own sake doesn’t help anyone, and is typically harmful.

...well, let's just leave it at: "I am glad you don't know what's going on in my life". I was about to type out something like this:

What is vague about the notion of productive like: how can the documentation team help people learn Nix effectively? 

I'm a newcomer. It has been a really weird challenge to navigate learning Nix. I'm trying to think through why that is, based on my recent experience, and was trying to put in effort into contributing to Nix docs. I tried to help review a recent PR, and had some questions based on that. The answer to that question didn't entirely make sense to me, and I tried to be careful by writing out why I felt it didn't make sense to me, rather than merely say "that doesn't make sense". 
 
What is so *insincere* about that?

...but I don't think it would make a difference to say that, (trying to put on a positive hat) because you are not responding to me, you're responding to an amalgamation of your past experiences ("...much digital ink has been spilled already").

you are free to contribute to the unofficial wiki as you like

This is something I have explored, and my experience there suggests that you're saying I should contribute there not because it's a viable option that would be meaningful, but probably because:

• (more positively) you have not used it and don't know the story around it currently, or
• (more negatively) you are politely telling me to "fudge off".

lifting useful content from the wiki for import into the official docs is a project some of us are interested in taking on at some point, but the team is usually only 3 or 4 part time and inconsistently-available contributors in any given week, with most of these volunteering. Resource constraints are severe.

I think you misread which wiki it is that I suggest a documentation team might eventually lift content from (it is not the unofficial one)...and the rest is irrelevant given that.

Onboarding new users has been a goal by both this team and the broader project/ecosystem, but is considered by some (myself among them)to be an anti-goal: users do not necessarily contribute, which is what the project (not just docs, everything) actually needs to flourish.

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. Also, we do not need 99/100 new users contributing back; having 1/10.000 new users doing so is good enough...it's how open source works...

So, the meat of your point here is that the goal of teaching newcomers is an anti-goal for you (and apparently some others here too, e.g. maybe those who reacted with a ❤️ to your message). The Nix Documentation team should be explicit about this so that unwitting people like me don't mistake its goals. If I had known that, a lot of what I did write, I would have known not to write.

you are welcome to “grab a shovel”, as some of us say, and help with the documentation effort (or even better, the flakes stabilization/detangling effort). Meeting times are available on the calendar. Join us!

You're definitely helping me feel quite welcome! Also, just a few days ago, I explicitly posted here asking if anyone wanted an extra pair of hands/eyes to help write/review anything. I didn't receive a response. So...I engaged on my own...

I say “detangling” above because flakes are so convoluted as to be difficult to document, and not for lack of trying; see any number of blog posts by various people on this topic, and the fact that we are still having this discussion
everything is political and many decisions are absolutely made based on aesthetic sensibilities. It is a fact that many involved in this work just don’t like the miserable little pile of features we call “flakes”today, and believe those pieces should be included in nix in a different form. Much digital ink has been spilled on this already

I'm not sure why you put these two points last, and I am also not sure I understand why you bothered to write anything else above it (apart from "onboarding newcomers is an anti-goal"). These two points alone are enough to answer all my questions.

I didn't even have a solid opinion on Nix flakes. I only know about them (and therefore used them) because of the Nix resources I ran into which were most approachable. (In particular: https://fasterthanli.me/series/building-a-rust-service-with-nix/part-10)

I was just confused about "why the thing people seem to be using the most" is not the thing we are also documenting.

For me at least, flakes are no more confusing than any other part of Nix, and I think most of the confusion around flakes is the same as for any other part of Nix: 1) lack of cohesion around how something ought to be done (there always seem to be a bunch of different ways) and 2) lack of discoverability through reading code alone, because of the lack of a typing system, and the existence of syntactic sugar/"magic features" that hide important connecting logic (e.g. how a certain variable is passed between certain contexts).

I'm totally willing to believe that flakes are more confusing, and are horrible. I just don't have enough experience, and in particular: I happened to (by chance) not run into high quality tutorials that don't involve flakes. I also ran into discussion (on news.ycombinator.com) about how flakes make Nix much easier to work with...

So, uh, yeah...

I guess I have to ask: you haven't made it clear how common the anti-flake/anti-newcomer view is. Is this official policy for the Nix project as a whole?

• If yes, why is it just not written clearly, so that simpletons like me would have known not to bother with reading about flakes and instead focus on the non-flakes way? (And also to not bother trying to write about how the docs aren't currently working well. Well, yeah, they aren't, because...their goal is not to help me; and that's okay!)
• If not, then I wonder: are you a part of the Nix docs team? If so, why are you engaging in an official team that you are anti-oriented with? Wouldn't it be healthier for you, and for the Nix project, if you put your efforts elsewhere (e.g. writing blog posts/making a No-Flakes-Here Nix Wiki/forking Nix)?

... notion of productive like: how can the documentation team help people learn Nix effectively?

This is indeed a goal, just not the only goal, and we're stretched so thin as to have to pick just one.

... telling me to "fudge off"

Not at all, in fact I welcome any new energy to this corner of the project -- I would be thrilled for you to join and help us! Just, the unofficial wiki is precisely the place where one can make wiki-style contributions. Now speaking for others: we see no reason to duplicate that effort, and instead focus on producing what we believe to be higher quality (in particular, more narratively-consistent) materials, like today's nix.dev.

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.

Also, we do not need 99/100 new users contributing back; having 1/10.000 new users doing so is good enough

We already have 1/10000 users contributing; the entire project ecosystem is sustained by the heroic efforts of fewer than 100 people.

... the goal of teaching newcomers is an anti-goal for you

Teaching newcomers to contribute is my goal, at this point. You can convince yourself of this by checking my more recent (albeit some months ago due to significant life changes) contributions, particularly in the "packaging existing software" tutorial and the draft Nixpkgs contribution tutorial that follows (PR 696 could use your help!).

... a few days ago, I explicitly posted here asking if anyone wanted an extra pair of hands/eyes to help write/review anything. I didn't receive a response

Sincerely: my apologies for this. We are all tremendously busy, and frequently are not able to appropriately reply. We will always welcome extra help - please join the next team meeting at 15:00 UTC!

I was just confused about "why the thing people seem to be using the most" is not the thing we are also documenting.

Indeed this is a giant problem: the thing people are using the most is also the most broken. This is not really even my opinion, but a matter of technical fact. I even use flakes for my own system configurations, but this is still the case largely because I, like so many, adopted that workflow without any awareness of the problems lurking beneath the surface (also at the surface; flake.nix is not even a valid Nix file!)

For me at least, flakes are no more confusing than any other part of Nix

For me too! But this is really because the whole ecosystem generally has poor documentation.

... lack of discoverability through reading code alone, ... lack of a typing system, ... "magic features" that hide important connecting logic

Oh yes. You cannot possibly imagine how strongly I agree here. I think we'll be friends after all :)

... discussion (on news.ycombinator.com) about how flakes make Nix much easier to work with

Some parts, certainly! Flakes have a lot of good ideas, just sort of all crammed into the same space, unfortunately. They deserve much more love from dedicated contributors who can separate out the various concerns and make them into proper Nix features, rather than an unspecified informal soft fork living in the same codebase, like a sad vampire.

... put your efforts elsewhere (e.g. writing blog posts

I've deleted mine, actually. There are too many as it is.

... making a No-Flakes-Here Nix Wiki

nix.dev is almost this, but is really more a No-Flakes- Yet un-Wiki. This isn't a holy war; in fact you will likely find that some of the biggest detractors of flakes are also some of the most enthusiastic about the utility they (could, and were intended to) bring. We all want reproducibility and easy extension of Nix magic into new domains!

... forking Nix

I prefer to avoid making unilateral decisions like this (for example, by spending months moving PRs with the team instead of firing off blog posts solo every morning).

In reply to @proofconstruction:matrix.org

... the goal of teaching newcomers is an anti-goal for you

Teaching newcomers to contribute is my goal, at this point. You can convince yourself of this by checking my more recent (albeit some months ago due to significant life changes) contributions, particularly in the "packaging existing software" tutorial and the draft Nixpkgs contribution tutorial that follows (PR 696 could use your help!).

I agree that this is super important too, because it was definitely a struggle for me to figure this out. I would be very happy to have a look at PR 696 and leave a review.

I also benefited from using nix-init (just to check out what it generates in order to help me learn Nix packaging patterns, or to use what it generates as a template for further extension)...and was quite disappointed I discovered that rather indirectly (someone was nice enough to tell me about it here when I was struggling to package something).

So, when I see that mentioned by zmitchell as something you might consider inserting in #696, I heartily agree!

In reply to @proofconstruction:matrix.org

... the goal of teaching newcomers is an anti-goal for you

Teaching newcomers to contribute is my goal, at this point. You can convince yourself of this by checking my more recent (albeit some months ago due to significant life changes) contributions, particularly in the "packaging existing software" tutorial and the draft Nixpkgs contribution tutorial that follows (PR 696 could use your help!).

I agree that this is super important too, because it was definitely a struggle for me to figure this out. I would be very happy to have a look at PR 696 and leave a review (edit: I did just finish doing that!)

I also benefited from using nix-init (just to check out what it generates in order to help me learn Nix packaging patterns, or to use what it generates as a template for further extension)...and was quite disappointed I discovered that rather indirectly (someone was nice enough to tell me about it here when I was struggling to package something).

So, when I see that mentioned by zmitchell as something you might consider inserting in #696, I heartily agree!

In reply to @proofconstruction:matrix.org

... telling me to "fudge off"

Not at all, in fact I welcome any new energy to this corner of the project -- I would be thrilled for you to join and help us! Just, the unofficial wiki is precisely the place where one can make wiki-style contributions. Now speaking for others: we see no reason to duplicate that effort, and instead focus on producing what we believe to be higher quality (in particular, more narratively-consistent) materials, like today's nix.dev.

I am inspired to suggest an alternative to the whole wiki thing, after reading PR#696.

I guess I'm wondering: why don't we just hit the accept button on the decent suggestions made by infinisil and zmitchell, and then just merge the darn thing? It's really good enough as is! It shouldn't have stayed as long as it has in PR review mode...and I think that's what I crave the most when I ask for a wiki.

I know how much my perfectionism gets in the way of getting something completed (or even started), and recently circumstances in life have forced me to accept that "it feels better to just not care"...surprisingly, this made me more productive, not less...

Wiki has a culture that enables that, but maybe it's a silly excuse to want to wait for a wiki to solve our problem there, when we could just....merge things faster 😅

In reply to @infinisil:matrix.org
Speaking of which, I think https://github.com/NixOS/nix.dev/pull/645 is now ready to be merged (we agreed to merge it once the headers are updated), though CI fails, will fix

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.