I feel like it’s actually not that hard… if you can tell what advice is bad and shouldn’t be followed. Which I realize is a major catch-22 for new users.

My honest advice on Neovim (for everyone) is to do this:

• environment.systemPackages = [ pkgs.neovim ];
• Configure Neovim as you usually would (hand-written init.lua, Lazyvim installer, whatever)
• Ignore/Disable Meson and use shell.nix to get language servers and formatters instead (alternatively: enable nix-ld for Meson or Mise)
• Completely ignore all the wrapper garbage like programs.neovim, nixvim, nvf, nixCats, and all the others

The last one is important. You can try all you want to make the garbage work and it eventually will, at least kinda, but IMHO the very idea of what they’re trying to do is bad, ultimately making them a colossal waste of time.

I have less strong but overall similar feelings regarding Home Manager, those newly hyped wrapper managers and libraries, the “Dendritic Pattern”, etc. The NixOS community loves coming up with novel ways to shoot themselves in the foot.

There’s a manual, a discourse (forum) and a Matrix. And an unofficial subreddit and a Lemmy community. As well as two wikis and a large number of random people writing blog posts and tutorials.

This might be a hot take but honestly I think the documentation quality isn’t the problem. You can point to specific topics that aren’t well documented but that isn’t unusual. What’s unusual is how NixOS is designed and how working around its quirks requires close to distro maintainer levels of knowledge.

Most distros don’t require several pages of documentation on how to install a Python application. NixOS on the other hand…

This module is actually a bit of a pet peeve of mine and a big reason I soured on Home Manager in general…

You inevitably end up writing chimera configurations like this:

# home.nix
programs.sway = {
  enable = true;
  
  # not supported by module - need to use escape hatch
  # good luck getting your editor to syntax highlight this snippet btw
  extraConfig = /* swayconfig */ ''
    bindgesture swipe:right workspace prev
    bindgesture swipe:left workspace next
  '';
};

programs.waybar = {
  enable = true:

  # can't do that in Nix
  style = /* css */ ''
    window#waybar {
      background: #16191C;
      color: #AAB2BF;
    }
  '';
};

# configuration.nix
# need to enable Sway a second time so the display manager can see it
# this may also install a second Sway if you fuck up your HM setup
programs.sway.enable = true;

and in exchange for this you get:

• 30s+ iteration times for basic changes like keybinds
• No ability to copy paste config snippets from READMEs/Wikis (unless you use home.file/extraConfig escape hatches)
• No ability to edit configuration in scripts (breaks a lot of theming functionality in “shells” like DMS, Noctalia, etc.)
• More ways to write configs that look right but don’t quite work or just do dumb things (extra Nixpkgs imports, duplicated packages, WMs that aren’t visible to the DM, etc.)

Alternatively you could just use a dotfile manager like rcm or stow or chezmoi like everyone not on NixOS+HM and not have to deal with any of this.