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.