In reply to @asymmetric:matrix.dapp.org.uk
has anyone had a chance to look at this? https://github.com/NixOS/nix.dev/pull/797

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?