FAQ: what are flakes

[fricklerhandwerk]

this is indeed a frequently asked question.

the answer is an attempt to clarify concepts and link to the relevant reference documentation without getting into too much technical detail.

[zmitchell]

This is an explanation and thus no longer a recipe. This and #546 should probably live in a single file under the "concepts" section.

[fricklerhandwerk]

I don't fully agree but also don't disagree that it's not recipe material. The answer doesn't really explain anything, it just states the difference to classic Nix. I suggest parking it here regardless under FAQ, since it is supposed to live next to the other flakes answers.

We could still later split up the recipe answers and leave a general FAQ in a different section, which could be filled with other actual questions people have, such as how Nix relates to Docker.

[asymmetric]

Not familiar with the proposed structure nix.dev will have, but I'm in favor of putting this under "concepts" or something else. Agree it doesn't make sense under "recipes".

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/noob-question-what-is-nix-flakes/28206/3

[zmitchell]

Answers to questions like "what even is XYZ?" strike me as conceptual, understanding oriented materials, so it makes sense to me to put that in Concepts. I don't want this in the recipes section because we both agree it's not recipe material, meaning that at some point down the line we'll end up moving it. So, let's not make work for our future selves and put it somewhere else.

[fricklerhandwerk]

Discussed in Nix docs team meeting:

• @fricklerhandwerk: What if we rename "FAQ" to "How-to guides" instead and create a concept section, put flakes in there?
• @infinisil: Make "What is Flakes" link to the section in the concepts
• @fricklerhandwerk: What about e.g. "Why are flakes controversial"? It's an FAQ
• @zmitchell: Also move that to concepts
• @roberth: Would be good to have a compiled glossary, because people don't know where to look and some concepts cross project boundaries
  • @infinisil: Needs tooling
    • @fricklerhandwerk: Doubt it's worthwhile right now
• @fricklerhandwerk: Will create a concepts header with just the flakes section in it for now
  • @roberth: Should the concepts be migrated to glossary entries?
  • @zmitchell: Glossary entries should be short, concepts longer
  • @roberth: Seems more like a task for the individual projects
• @fricklerhandwerk: Need to teach people how to understand the ecosystem, how parts interact with each other. Should probably have a diagram or something in the concepts header/glossary
• decision: make a concepts section and add flakes in there as a first entry

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-05-25-documentation-team-meeting-notes-50/28459/1

[fricklerhandwerk]

Merging since the general direction was reviewed and agreed upon by the docs team. Details can be fixed forward.

Implemented changes as requested