@deliciouslytyped : “Cannot coerce set to string” is my arch nemesis.
@Shados : Thank you for demystifying propagation!
Would you mind adding this to the manual; or else would you object to me adding it?
I have a paper cut:
Many super useful functions are defined throughout Nixpkgs inside of let ... in blocks. This is great for functions that truly need to be kept local for a particular file; but often the ability to import and re-use these functions would be super convenient.
Often these functions are specific to a collection of packages so they don’t make it into lib, which makes sense; but something like “exports” in a file or at the very least a migration of many functions into lib.nix in many directories would be awesome. A prime example is “documentation” which has loads of useful functions that I often copy and paste parts of into peojects to collect info about my system. I have a post called “nix fuzzy search” or something along those lines on this board that demonstrates this.
I would be more than happy to implement “exports” or start migrating things into lib.nix if there is supporting consensus.
Another “hot take”:
Documentation for a subsection of Nixpkgs should consistently appear in a folder’s README.md. The Nixpkgs/NixOS manual should be built by sourcing all of or sections of these files.
I have been using Nix for well over a year and frankly I have never added to our documentation because it feels like this “other thing” that I need to learn how to use. I honestly feel like from a “design/contribution experience” perspective Nix Manuals feels divorced from the actual packages and tools. If I’m hacking around in a folder, I expect a README.md to be nearby for me to reference or add things to as I learn and contribute. If I’m being perfectly honest I couldn’t tell you off the top of my head where the documentation files are kept in the repo, but can easily recall where many packages and modules reside. I may be alone in this regard, but if I’m not, this might help explain why we often end up with outdated or non-existant documentation.
JFC I know that these files often exist. On that note these files are sometimes more up to date than our Manuals; sourcing them into the Manual’s build rather than having “two versions” seems reasonable. I think that altering the pattern for how we build the manual and write documentation, to make it more approachable and consistent could help to solve some of the documentation issues that we face.
Imagine this radical scenario if you will:
You open Nixpkgs on GitHub’s webpage and dive into the haskell-modules directory; magically a README.md appear as nicely formatted HTML in your browser 
. You open the lib directory and GitHub serves up some beautifully highlighted usage examples, and helpful tips left by contributors of days past 
. Before I lose you in this fantasy lets recollect.
I often make quick tweaks to other repo’s docs directly through GitHub’s web UI when I’m browsing, and it would be a delight to have that same convenience in our repo. If we want better documentation, I suggest we begin by making it more convenient to contribute documentation.
Follow up:
I started digging into the documentation build process and discovered that it contains/builds some fantastic Markdown documents for various subsections of the repo, that would be perfect to put into the relevant parts of the repository! Currently the process (for some parts) is : (XML DocBook ↔ Markdown) → HTML. I am basically suggesting that we instead do : Markdown → XML DocBook → HTML. The repo has both Markdown and XML now in some cases that hold identical content.
This process/pattern does not exist for all parts of the manual, and it’s not immediately clear to me why it bothers building the markdown files at all honestly since it’s not as if most people are ever discover them. You can find the existing ones at docs/language-frameworks/*.section.md and docs/introduction.chapter.md. I want to generate these for the remaining sections of the manual, disperse them to their relevant directories, and then alter the manual build script to perform the aforementioned Markdown → XML transformation.
Edit: I had initially thought that the Markdowns were generated from XML, but after looking back at a fresh version of the repo I realized that both versions exist, holding identical contents.
Edits: Merged my multiple comments, and “Follow Up”.
It seems like there are docs for getting started and docs supporting “power users” but very little in the middle. Especially for those of us who like and use NixOS but for whom our day job is something else so we won’t become power users anytime soon (without help).
, mostly because it’s undocumented (another papercut for the list!). I’ll amend my previous post in the morning.