From 30d49efe57223c581d1cd147f4164bf8fdd93df5 Mon Sep 17 00:00:00 2001 From: Emile Clark-Boman Date: Sat, 2 Aug 2025 17:45:24 +1000 Subject: [PATCH] add introduction section to GUIDE.md --- GUIDE.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/GUIDE.md b/GUIDE.md index 95180b6..7666492 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -1,3 +1,61 @@ +# The Nix Documentation Situation +The Nix documentation situation is notorious bad. It's difficult to find +a concise answer with detailed justification/explanation. And most people +(myself included) tend resort to the [ArchWiki](https://wiki.archlinux.org). +> [!NOTE] +> The [Nix documentation team](https://nixos.org/community/teams/documentation) has an incredibly difficult job. + +Unlike the *centralised* [ArchWiki](https://wiki.archlinux.org), the Nix ecosystem +is incredibly large: +1. **Nix** (the package manager) +2. **Nix/NixLang** (the programming language) +3. **Nixpkgs** (the package repository) +4. **NixOS** (the linux distribution) +5. **Home-Manager** (user environment management) +6. **NUR** (Nix User Repository, like the AUR but Nix!) +7. *and **many** more...* + +Often each project has its own website, wiki, styling, etc. There is tonnes +of information available online but its so hard to find it. + +**Notable organisations:** +1. NixOS Foundation (*official organisation that maintains Nix/Nixpkgs/NixOS*) +2. Nix Community (*unofficial community providing infrastructure/hosting/visibility for projects*) + +## About Me +I love and hate Nix simultaneously. + +Originally *(circa 2023)* I used Windows 10/11 exclusively for programming. +But this is tedious and my friend started mentioning Arch Linux. So with their +help I formatted a spare SSD and began my journey. + +But I **REALLY** like computers... I have servers, routers, 3 computers +actively powered in my bedroom, and *I believe* 8 laptops *currently* in my posession. + +Documenting **every** change I make to a system and spending a week +setting up a device I don't really care about isn't sustainable. +And then *(circa October 2024)* I learnt about NixOS... And now life is "easy". +But learning Nix/NixLang/Nixpkgs/NixOS/Home-Manager/blah-blah-blah was exhausting. +So now I'll try to simplify this learning curve for other newbies **<3** + + +## Nix/NixOS How To +### NixOS Documentation +Using "the" NixOS wiki is surprisingly confusing (at least it was for me). +Why? Because there are multiple and you probably won't realise the difference. + +**Main Wikis:** +> These are visually and structurally identical... And are both community run. +> But they're content does differ. [nixos.wiki] was created +> because ""[wiki.nixos.org] was too limiting with regards to wiki features". +1. [https://wiki.nixos.org] (the **official** NixOS wiki) +2. [https://nixos.wiki] (the **unofficial** user's wiki, community run) + + +**Other Resources:** +> [!TODO] + + ### Migrate to a Newer Version of Nixpkgs ```bash # Determine the channel name you're using