glossary: import terms from nixionary.org #400
Conversation
Nix is using a bunch of esoteric terms like "closure" and "realization" that can turn off newcomers. I'm assuming that having a good glossary can help with that. I always like a good glossary to speed-run a new project. <https://nixionary.org> was a little project I had for NixCon, to collect more of those words for the glossary.
zimbatm
requested review from
domenkozar and
fricklerhandwerk
as code owners
|
CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅ |
|
the CLA still attributes ownership to @domenkozar, is that by design? |
|
@zimbatm Yes, currently @domenkozar still holds the copyright for now. This will be reassigned to the foundation in the future. |
| Linux distribution based on Nix and Nixpkgs. | ||
| The name represents two things at the same time: | ||
|
|
||
| 1. The whole project and community. |
There was a problem hiding this comment.
That's not true and a reason for large amounts of confusion.
(Yes, it's how some people understand and use it, but it doesn't make it right or less confusing.)
There was a problem hiding this comment.
What is the name of the project and community then? The entry point domain is nixos.org.
I agree that it's confusing, that's why it's worth documenting it.
|
I have read the CLA Document and I hereby sign the CLA |
|
I'm trying to add definitions for a part of these terms to the Nix manual: Substituter already exists in the Nix manual' glossary. I'm not sure about the change overall. It's probably good to have multiple entry points for terms. But maybe it's enough to link to the terms' authoritative definitions (in their respective manuals) when they are used in texts. In any case we should not re-make the definition here, and rather link to the existing one. Sometimes we don't have (a good) one, like it was the case for the Nix language in the Nix manual, but that should be addressed first then. @lucperkins @yukiisbored what do you think? |
| A git repository containing a collection of 80000+ packages. See | ||
| <https://nixpkgs.org>. |
There was a problem hiding this comment.
Adding a link is good, more descriptions, I think, less so. Each project should just describe itself authoritatively, as a single source of truth. That description may change over time, no point tracking these things here.
| Attribute sets | ||
| Attribute sets represent a sorted collection of name/value pairs in the Nix | ||
| language. | ||
|
|
||
| Channels | ||
| Represents two things: | ||
| 1. Releases of nixpkgs built and pushed by Hydra. See | ||
| <https://status.nixos.org>. | ||
| 2. GC roots that are managed by `nix-channel`. | ||
|
|
||
| Closure | ||
| The closure is the tree of the dependencies of a derivation, and the | ||
| dependencies of the depencencies recursively. |
There was a problem hiding this comment.
These should go to the Nix manual's glossary.
|
I don't think it's a bad idea to have another glossary in nix.dev since I imagine they rarely change. Though, I'm not opposed to linking the definition on the Nix manual. |
|
I'm happy if you incorporate my work in any way that you think is useful. If you want to push all the definitions to the respective projects and then transform this glossary into a meta glossary, that's fine. Since you seem to be opinionated about it @fricklerhandwerk, I think the easiest would be for you to cannibalize my PR. That way we avoid too much back and forth. |
|
@zimbatm thanks, I appreciate the addition in general. Sorry, the tone here is usually quite to the point, and my comment was absolutely not to dismiss your effort. This is a strategic decision for the documentation team to make, I just have random opinions which are surely most often wrong. |
|
No worries, it makes sense to be opinionated for documentation, to give it a consistent feel. Please have a chat with the documentation team and let me know once you agree on the high-level direction. |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/tweag-nix-dev-update-40/23480/1 |
|
Oops, deleted my fork by mistake. Is it worth me re-opening a PR, or what do you want to do with that content? |
|
@NixOS/documentation-team |
|
Imo the nix.dev glossary should ideally be the combined glossaries of Nix itself, nixpkgs and NixOS, plus all of the general terms not mentioned anywhere else (like Nixpkgs, NixOS, etc.) I'm not sure how feasible this is though |
|
Imagine all the people who could have benefited from that Glossary, even if imperfect. It would be better than the current situation. And you can still move things around later? |
Nix is using a bunch of esoteric terms like "closure" and "realization"
that can turn off newcomers. I'm assuming that having a good glossary
can help with that. I always like a good glossary to speed-run a new
project.
https://nixionary.org was a little project I had for NixCon, to
collect more of those words for the glossary.