In reply to @infinisil:matrix.org
danielsidhion: Which meeting link did you try to join?

In reply to @infinisil:matrix.org
asymmetric: Would you still want to review nixdoc PRs?

In reply to @infinisil:matrix.org
asymmetric: Would you still want to review nixdoc PRs?

In reply to @infinisil:matrix.org
Just started working on a tutorial on how to select files for sources and the file set library: https://github.com/NixOS/nix.dev/pull/802 :)

In reply to @bzzm3r:matrix.org
Is there a team lead for the documentation team?

fricklerhandwerk:

I recently asked someone writing for the documentation team why they were mentioning niv (and not flakes), and related: why they were mentioning nix-build and not nix build in a tutorial that is ultimately going to live on nix.dev. They helpfully answered with the following: https://github.com/NixOS/nix.dev/pull/802#discussion_r1398526182

I would like to ask about the conclusions reached by the documentation team, as explained in the above posts. It is difficult for me (currently) to believe they actual facts rather than convenient fictions. Obviously, what I think does not matter, but I suppose perhaps that this gives me the room to speak freely.

In the explanation for why the documentation team is operating based on the currently agreed upon rules, the following underlying points are especially difficult for me to understand:

1. the belief that stabilization is a fixed goal, with associated objective metrics that let us determine how close we are to stabilization, rather than "stabilization" being a concept motivated by aesthetics (for a small team/single person) or politics (for a larger team).

This seems to ignore:

• that documentation is a part of the process of the aesthetic/political requirements that allows judgements regarding what is stable vs unstable; (also, as a consequence, decisions made by documentation teams regarding what should be documented are political decisions too.)
• that documentation (or lack thereof) contributes to how easy it is to "stabilize" (or destabilize) a feature.
• that it is possible for a feature's opposition to constantly change the requirements of the "is stabilized" condition, so that the feature is effectively never stabilized;
• that it is possible for something to be "stable" only because it is no longer being maintained, or that there is an instability inherent in the process of maintenance and incremental improvement.
• that we have objective measurements which allow us to conclusively determine that some aspects of Nix are stable, while others are not. Suppose we could come up with such a metric: then what goes into such a metric? Is it merely a matter of how frequently the function signatures change?

1. (if we ignore 1, and agree that stabilization is more objective than mere politics/aesthetics) the belief that if something is stabilized, it is easier to document; and conversely, the belief that if something is unstable, then it is harder to document

This seems to ignore that:

• something that is "stable" may be so convoluted, that it is difficult to document; conversely that something that is "unstable" may be much simpler conceptually.
• that documentation as en effort, is not separate from development, as an effort. It is possible, and also perhaps desirable, to ask that change authors accompany their work with some degree of documentation by default.

1. (again, if we agree to ignore 1) the belief that if something is stabilized, it is more relevant to document (therefore, should be prioritized in resource limited contexts)

This seems to ignore:

• there might be more important tasks than documenting what is stable:

For example, imagine we have a situation where the documentation team is resource-limited, and knowledge of the system tends to live mostly in the minds/actions of people, rather than being codified centrally.

Then it might make sense to capture as much of that informal information as possible as preparation for more targeted documentation efforts. The easiest way to do this is to open up an official wiki that is easy to contribute to (easy to write articles for). People can participate with ease both with respect to the presentation quality of what they contribute, and if they do not want to contribute, they can merely help improve the presentation quality. It is also easier to record disagreements on a particular area (see how the Arch Wiki handles this by showing small notification markers over controversial sections which give a quick summary of the controversy, and a link to where the discussion is being held).

A resource limited documentation team can also then benefit from the Wiki by lifting those parts which can be moulded/sharpened into fully official formal documentation.

Why has it been so hard to get Mic92's Wiki revival hosted?

• that it is important to consider that part of the purpose of documentation is to help onboard newcomers. So it is important to consider what they are being onboarded onto. Is it what is currently stable? Or what is soon to be stabilized? The answer to this question is more important in determining what ought to be documented first, instead of "what is stable right now"?

• that part of the purpose of documentation is to help build up the community, therefore if it contributes to areas of confusion by further confusing matters, then it might be anti-productive (which is worse than being non-productive)?

• that a resource constrained documentation ought to also think about how existing pieces of disparate information can be re-moulded into material of higher quality, rather than only create documentation de novo. As a first step, collecting a library of links to useful documentation that are vetted by the documentation for quality would be helpful not only in providing information, but also providing a list of resources that documentation team members have the permission to re-mould into official documentation (with the authors' permission; if an author chooses not to give permission, their work need not be included).

• that a resource constrained documentation team ought to figure out how it can be less resource constrained (i.e. have more participants), and prioritize activities which lead to natural growth of the team, rather than prioritize based on stable/unstable?

fricklerhandwerk:

I recently asked someone writing for the documentation team why they were mentioning niv (and not flakes), and related: why they were mentioning nix-build and not nix build in a tutorial that is ultimately going to live on nix.dev. They helpfully answered with the following: https://github.com/NixOS/nix.dev/pull/802#discussion_r1398526182

I would like to ask about the conclusions reached by the documentation team, as explained in the above posts. It is difficult for me (currently) to believe they are actual facts rather than convenient fictions. Obviously, what I think does not matter, but I suppose perhaps that this gives me the room to speak freely.

In the explanation for why the documentation team is operating based on the currently agreed upon rules, the following underlying points are especially difficult for me to understand:

1. the belief that stabilization is a fixed goal, with associated objective metrics that let us determine how close we are to stabilization, rather than "stabilization" being a concept motivated by aesthetics (for a small team/single person) or politics (for a larger team).

This seems to ignore:

• that documentation is a part of the process of the aesthetic/political requirements that allows judgements regarding what is stable vs unstable; (also, as a consequence, decisions made by documentation teams regarding what should be documented are political decisions too.)
• that documentation (or lack thereof) contributes to how easy it is to "stabilize" (or destabilize) a feature.
• that it is possible for a feature's opposition to constantly change the requirements of the "is stabilized" condition, so that the feature is effectively never stabilized;
• that it is possible for something to be "stable" only because it is no longer being maintained, or that there is an instability inherent in the process of maintenance and incremental improvement.
• that we have objective measurements which allow us to conclusively determine that some aspects of Nix are stable, while others are not. Suppose we could come up with such a metric: then what goes into such a metric? Is it merely a matter of how frequently the function signatures change?

1. (if we ignore 1, and agree that stabilization is more objective than mere politics/aesthetics) the belief that if something is stabilized, it is easier to document; and conversely, the belief that if something is unstable, then it is harder to document

This seems to ignore that:

• something that is "stable" may be so convoluted, that it is difficult to document; conversely that something that is "unstable" may be much simpler conceptually.
• that documentation as en effort, is not separate from development, as an effort. It is possible, and also perhaps desirable, to ask that change authors accompany their work with some degree of documentation by default.

1. (again, if we agree to ignore 1) the belief that if something is stabilized, it is more relevant to document (therefore, should be prioritized in resource limited contexts)

This seems to ignore:

• there might be more important tasks than documenting what is stable:

For example, imagine we have a situation where the documentation team is resource-limited, and knowledge of the system tends to live mostly in the minds/actions of people, rather than being codified centrally.

Then it might make sense to capture as much of that informal information as possible as preparation for more targeted documentation efforts. The easiest way to do this is to open up an official wiki that is easy to contribute to (easy to write articles for). People can participate with ease both with respect to the presentation quality of what they contribute, and if they do not want to contribute, they can merely help improve the presentation quality. It is also easier to record disagreements on a particular area (see how the Arch Wiki handles this by showing small notification markers over controversial sections which give a quick summary of the controversy, and a link to where the discussion is being held).

A resource limited documentation team can also then benefit from the Wiki by lifting those parts which can be moulded/sharpened into fully official formal documentation.

Why has it been so hard to get Mic92's Wiki revival hosted?

• that it is important to consider that part of the purpose of documentation is to help onboard newcomers. So it is important to consider what they are being onboarded onto. Is it what is currently stable? Or what is soon to be stabilized? The answer to this question is more important in determining what ought to be documented first, instead of "what is stable right now"?
• that part of the purpose of documentation is to help build up the community, therefore if it contributes to areas of confusion by further confusing matters, then it might be anti-productive (which is worse than being non-productive)?
• that a resource constrained documentation ought to also think about how existing pieces of disparate information can be re-moulded into material of higher quality, rather than only create documentation de novo. As a first step, collecting a library of links to useful documentation that are vetted by the documentation for quality would be helpful not only in providing information, but also providing a list of resources that documentation team members have the permission to re-mould into official documentation (with the authors' permission; if an author chooses not to give permission, their work need not be included).
• that a resource constrained documentation team ought to figure out how it can be less resource constrained (i.e. have more participants), and prioritize activities which lead to natural growth of the team, rather than prioritize based on stable/unstable?

fricklerhandwerk:

I recently asked someone writing for the documentation team why they were mentioning niv (and not flakes), and related: why they were mentioning nix-build and not nix build in a tutorial that is ultimately going to live on nix.dev. They helpfully answered with the following: https://github.com/NixOS/nix.dev/pull/802#discussion_r1398526182

I would like to ask about the conclusions reached by the documentation team, as explained in the above posts. It is difficult for me (currently) to believe they are actual facts rather than convenient fictions. Obviously, what I think does not matter, but I suppose perhaps that this gives me the room to speak freely.

In the explanation for why the documentation team is operating based on the currently agreed upon rules, the following underlying points are especially difficult for me to understand:

ONE the belief that stabilization is a fixed goal, with associated objective metrics that let us determine how close we are to stabilization, rather than "stabilization" being a concept motivated by aesthetics (for a small team/single person) or politics (for a larger team).

This seems to ignore:

• that documentation is a part of the process of the aesthetic/political requirements that allows judgements regarding what is stable vs unstable; (also, as a consequence, decisions made by documentation teams regarding what should be documented are political decisions too.)
• that documentation (or lack thereof) contributes to how easy it is to "stabilize" (or destabilize) a feature.
• that it is possible for a feature's opposition to constantly change the requirements of the "is stabilized" condition, so that the feature is effectively never stabilized;
• that it is possible for something to be "stable" only because it is no longer being maintained, or that there is an instability inherent in the process of maintenance and incremental improvement.
• that we have objective measurements which allow us to conclusively determine that some aspects of Nix are stable, while others are not. Suppose we could come up with such a metric: then what goes into such a metric? Is it merely a matter of how frequently the function signatures change?

TWO (if we ignore ONE, and agree that stabilization is more objective than mere politics/aesthetics) the belief that if something is stabilized, it is easier to document; and conversely, the belief that if something is unstable, then it is harder to document

This seems to ignore that:

• something that is "stable" may be so convoluted, that it is difficult to document; conversely that something that is "unstable" may be much simpler conceptually.
• that documentation as en effort, is not separate from development, as an effort. It is possible, and also perhaps desirable, to ask that change authors accompany their work with some degree of documentation by default.

THREE (again, if we agree to ignore 1) the belief that if something is stabilized, it is more relevant to document (therefore, should be prioritized in resource limited contexts)

This seems to ignore:

• there might be more important tasks than documenting what is stable:

For example, imagine we have a situation where the documentation team is resource-limited, and knowledge of the system tends to live mostly in the minds/actions of people, rather than being codified centrally.

Then it might make sense to capture as much of that informal information as possible as preparation for more targeted documentation efforts. The easiest way to do this is to open up an official wiki that is easy to contribute to (easy to write articles for). People can participate with ease both with respect to the presentation quality of what they contribute, and if they do not want to contribute, they can merely help improve the presentation quality. It is also easier to record disagreements on a particular area (see how the Arch Wiki handles this by showing small notification markers over controversial sections which give a quick summary of the controversy, and a link to where the discussion is being held).

A resource limited documentation team can also then benefit from the Wiki by lifting those parts which can be moulded/sharpened into fully official formal documentation.

Why has it been so hard to get Mic92's Wiki revival hosted?

• that it is important to consider that part of the purpose of documentation is to help onboard newcomers. So it is important to consider what they are being onboarded onto. Is it what is currently stable? Or what is soon to be stabilized? The answer to this question is more important in determining what ought to be documented first, instead of "what is stable right now"?
• that part of the purpose of documentation is to help build up the community, therefore if it contributes to areas of confusion by further confusing matters, then it might be anti-productive (which is worse than being non-productive)?
• that a resource constrained documentation ought to also think about how existing pieces of disparate information can be re-moulded into material of higher quality, rather than only create documentation de novo. As a first step, collecting a library of links to useful documentation that are vetted by the documentation for quality would be helpful not only in providing information, but also providing a list of resources that documentation team members have the permission to re-mould into official documentation (with the authors' permission; if an author chooses not to give permission, their work need not be included).
• that a resource constrained documentation team ought to figure out how it can be less resource constrained (i.e. have more participants), and prioritize activities which lead to natural growth of the team, rather than prioritize based on stable/unstable?

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

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

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. Except, I didn't advertise them, 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)?