Ideas on documentation improvements

[Adda0]

In this discussion, I will outline ideas for improving the documentation, one per comment.

I assume the documentation is meant for completely new Nix users as well. I tried to approach the documentation as if I knew nothing / only very little about Nix and the whole ecosystem.

[Adda0]

https://system-manager.net/main/how-to/install/#option-2-determinate-systems-installer

• detNix installation does not support native Nix anymore (or at least it will be removed soon; I think it already was removed).
  • But it seems to be working with DetNix without problems so far.
  • I had to manually remove /etc/nix/nix.conf so system-manager can modify it on its own after initial setup via the init command, but there was a nice friendly red error in the system-manager output. Still, a warning in the documentation would be nice.

[Adda0]

https://system-manager.net/main/tutorials/getting-started/

• in system.nix: attrset config is used: { config = { …}; }, while in apps.nix: config attrset is omitted: { … }, but sometimes even { config = {…} } occurs in the examples. This needs to be unified and probably mention that both approaches are possible.

[Adda0]

https://system-manager.net/main/tutorials/getting-started/ and all other tutorials

• When re-running system-manager, do I have to run nix run github:numtide/system-manager -- ... all the time? No shorter command to be accessible after system-manager init? New users might get confused and discouraged when having to repeatedly write a long command with github: flake ref. I really think there should be an officially promoted shorter command once system-manager is activated for the first time. It is not a trivial problem, though.
• Maybe link to https://system-manager.net/main/how-to/install/#optional-installing-system-manager-locally for the second invocation of the lengthy command. Something like " 💡 Do not want to write the whole long command repeatedly? Set up the command locally with [link]."

[Adda0]

https://system-manager.net/main/tutorials/getting-started/ and other tutorials.

• New users will be confused whether they always need to re-run source … or exec <shell> after rebuilding the configuration with system-manager. This should be clarified, and subsequent instructions for rebuilding the configuration should all adhere to it.

[Adda0]

https://system-manager.net/main/tutorials/getting-started/#understanding-the-config-attribute-set

When System Manager runs, with the help of the Nix language, you can have multiple config attribute sets, and System Manager combines them into a single attribute set. This allows you to have different setups in separate files, and simply combine them side by side, only having to add on to this line:

• "You can have multiple config attrsets"
  • Where? Unclear. Say something about modularity where modules can complement each other, and settings from modules are unified…?

[Adda0]

https://system-manager.net/main/tutorials/getting-started/

• When explaining Nix syntax, linking to an overview or summary would be greatly beneficial. Something like:
  • https://nixos.org/guides/nix-pills/04-basics-of-language.html, and/or
  • https://nix.dev/tutorials/nix-language.html.

[Adda0]

https://system-manager.net/main/tutorials/getting-started/#understanding-the-config-attribute-set

• Link to multi-file configuration tutorial when explaining modularisation of Nix: combining attrsets config, where users confused about what multiple config attrsets mean might get a better idea of what modularisation means in this case.
• The term "attribute sets" is used without much explanation of what attrsets are. Without prior knowledge, people might get lost. Hence, the point about adding a link to some Nix language overview.

[Adda0]

https://system-manager.net/main/tutorials/multi-file-config/#step-3-update-your-flake

• Inline attrsets/modules shown in the flake.nix were never introduced, I believe. Surprising for new users. Maybe explain how it is the same as taking he contents of an existing file and placing it verbatim in the list?

        modules = [
          { nixpkgs.hostPlatform = "x86_64-linux"; }
          ./modules/packages.nix
          ./modules/services.nix
        ];

[Adda0]

https://system-manager.net/main/tutorials/multi-file-config/#step-2-create-separate-module-files

• Maybe instead of including modules/packages.nix and modules/services.nix, introduce modules/default.nix (which includes all the ./packages.nix , ./services.nix , etc. inside) and explain including modules = [ ./modules ] (looking for default.nix)? Useful concept, and oftentimes preferred approach.

[Adda0]

https://system-manager.net/main/tutorials/multi-file-config/#next-steps

Learn about folder organization patterns

• Links to installation guide. That is, I presume, not intentional?