In reply to @fricklerhandwerk:matrix.org
Overall it's not that bad in terms of size, looks pretty mechanical.

In reply to @johannes.kirschbauer:scs.ems.host
djacu: no the RFC is not strict in those terms. danielsidhion and me worked on what is more like conventions. There are other files in lib that use commonmark already in comments for reference

Ah okay. I saw things like this and wasn't sure.

# Inputs

    `f`
    : 1\. Function argument

I do like it though!

Hey. I'm a new NixOS user, already trying to heavily use the documentation. :) Someone pointed out to me that there's two wikis, with a difference. I've been looking at the NixOS manual, but had missed at least this.

Now I'm looking for glossaries. Is this the best we have? https://nix.dev/manual/nix/2.23/glossary.html#gloss-store-derivation

I could perhaps contribute (as in I can make a PR) by... Hm. My initial idea would be to at least

1. Sort it; now it's hard to find anything in it
2. I actually think that page could use a TOC. Or some kind of a layout change, I'm not sure. Now if I want to find something on it, my best bet is to do a search in browser, and that hits other mentions of the word.

Also I feel it's missing quite a few pieces of terminology that I've run into a lot the past few days. I think at least module, option, store, package, flake, home manager.

Then I don't know what of those are Nix and what are NixOS. Is there a hard split between "Nix documentation" and "NixOS documentation"? (Though if we expect a newcomer to know which manual to look in, maybe that's a problem in itself?)

Hey. I'm a new NixOS user, already trying to heavily use the documentation. :) Someone pointed out to me that there's two wikis, with a difference. I've been looking at the NixOS manual, but had missed at least this.

Now I'm looking for glossaries. Is this the best we have? https://nix.dev/manual/nix/2.23/glossary.html#gloss-store-derivation

I could perhaps contribute (as in I can make a PR) by... Hm. My initial idea would be to at least

1. Sort it; now it's hard to find anything in it
2. I actually think that page could use a TOC. Or some kind of a layout change, I'm not sure. Now if I want to find something on it, my best bet is to do a search in browser, and that hits other mentions of the word.

Also I feel it's missing quite a few pieces of terminology that I've run into a lot the past few days. I think at least module, option, store, package, generation, flake, home manager.

Then I don't know what of those are Nix and what are NixOS. Is there a hard split between "Nix documentation" and "NixOS documentation"? (Though if we expect a newcomer to know which manual to look in, maybe that's a problem in itself?)

Hey. I'm a new NixOS user, already trying to heavily use the documentation. :) Someone pointed out to me that there's two wikis, with a difference. I've been looking at the NixOS manual, but had missed at least this.

Now I'm looking for glossaries. Is this the best we have? https://nix.dev/manual/nix/2.23/glossary.html#gloss-store-derivation

I could perhaps contribute (as in I can make a PR) by... Hm. My initial idea would be to at least

1. Sort it; now it's hard to find anything in it
2. I actually think that page could use a TOC. Or some kind of a layout change, I'm not sure. Now if I want to find something on it, my best bet is to do a search in browser, and that hits other mentions of the word.

Also I feel it's missing quite a few pieces of terminology that I've run into a lot the past few days. I think at least module, option, store, package, generation, channel, flake, home manager.

Then I don't know what of those are Nix and what are NixOS. Is there a hard split between "Nix documentation" and "NixOS documentation"? (Though if we expect a newcomer to know which manual to look in, maybe that's a problem in itself?)

Each of those things has a reference manual, all of them linked in nix.dev. The reference manuals are supposed to only show what’s there, with a few examples, while nix.dev is for tutorials and guides. The separation is not as clean in reality, because there are a lot of pieces to the puzzle, and the time people spent so far was not enough to untangle everything.

Home Manager is unfortunately not listed there yet, and the only reason is that no one got to explain, within the narrative arc we’re building, which role it plays and how to start out.

In reply to @proofconstruction:matrix.org
Welcome! For suggestions, typically they are made here, in a GitHub Issue, or by implementing the change and making a pull request to the appropriate repository. In all cases there will be an associated thread of comments and follow up suggestions.