2024-02-22 Documentation team meeting notes #110


  • PRs ready to merge?
  • @danielsidhion: NixOS manual ownership and maintainership?
  • Google Season of Docs

PRs ready to merge

NixOS manual ownership

  • @danielsidhion is going through Nixpkgs PRs and is improving style and consistency in small increments
    • currently not touching NixOS documentation
    • also working with @hsjobeki on docs generation and possibly splitting the manual(s) into separate pages
    • not clear who maintains the NixOS manual
  • Nominated @danielsidhion for Nixpkgs commit access to maintain the Nixpkgs manual

Google Season of Docs


I’ve noticed that there’s few if any comments in the C++ code. What’s the story there?

I assume you’re talking about Nix. Yes, and many names don’t match any more to what the code does. It’s just the way it has developed. Sometimes when I explore the code, I make tiny refactorings or add comments to leave traces for the next person to hold on to. Even if these don’t get merged, it’s a good opportunity to discuss what you’ve learned with code owners.

Gotcha. I was writing my own fetcher recently and struggled a bit because there’s no docs on what the contracts/idioms are, who’s supposed to set the scheme on the input, etc.

The input schema is implicit in the implementation. I already frowned on that in maintainer discussions around stabilising ferchTree a couple of months ago. We considered adding a declarative schema mechanism, and it would still be really nice for reasoning and documentation, but in practice ain’t nobody got time for that.