Documentation Overhaul

[Pacman99]

Intro

I'm writing this up in reference to #451 #372 and #313 The documentation and onboarding user story is horrible. After the digga transition, #430, and all sorts of changes before, the documentation doesn't reflect the current state of what digga can do and what it means to users. I realize I'm creating yet another issue for something that has been repeated before. I'm hoping this issue can serve as a thread to collect specific action items to improve the documentation.

Target Users

I just want to start with the type of people we're writing the documentation for.

• They are completely new to NixOS who would want to use digga to setup their pc or server. We need to explain every NixOS and nix concept for such a user.
• They are familiar with NixOS but new to flakes. They should be provided with escape routes to skip the explanations they already know and get started quickly. There should be explanations on converting your configuration.nix to the flake. They can start by moving everything to the host directory, thhttps://github.com/divnix/digga/tree/main/doc/starten start factoring out code into profiles, modules, pkgs, etc.
• Advanced user who wants to use digga to improve their repo. They just need a way to get started and explanation on what the purpose of every digga concepts. They will likely know what they want from digga and how to use it.

Action items

• [ ] Export more templates
• [ ] Explain different templates and give users the choice to clone any one of them
• [ ] Use comments or README in templates to document what will need to be changed. We can't just say clone devos and start building, there are more steps after that. The digga docs itself could explain where to start when customizing
• [ ] Write a section on customizing the template to your needs, explaining what could be changed and deleted based on what you want.
• [ ] Fix and outline process for bootstrapping on a new host, current instructions don't work. They should be changed to reference nixos-generator
• [ ] The iso and bootstrap host section should be connected, with one linking to the other. They also need updates and better explanations
• [ ] Explain what commands mean and nix concepts through guides
• [ ] Add guides on using the new digga based setup, like how do you rebuild, how do you deploy to a remote system.
• [ ] #313

If anyone is interested in helping please post here, I wanted to get these listed out, I'm not sure when I'll get around to working on them. And I'm definitely missing things, so feel free to edit the issue or let me know if you would like to add more goals.

[montchr]

This is great! And definitely very important.

[montchr]

One question (plus sub-questions 😆) I have, which could be added to this list: what is the current state of bud? Is it worth improving or are there plans to ditch it? If it's sticking around, what needs improvement? Clarity on that would help guide decisions about approaches to documentation.

[anthr76]

FWIW with considering this issue https://github.com/NixOS/nixpkgs/issues/169193 bud in it's current state is somewhat broken,

[blaggacao]

FWIW, std just landed ADR & Docs nudging:

https://github.com/divnix/std/blob/2e761e3c3271d37ffeffabda8c5d1552eb1f3189/cells/std/devshellProfiles.nix#L24-L68

I'm also planning to leverage these two projects shortly for extra UX:

• https://github.com/JoelCourtney/mdbook-kroki-preprocessor
• https://github.com/dvogt23/book-summary

[Pacman99]

what is the current state of bud?

Current plans are to ditch it. This means removing any reference to bud in docs. bud build should be replaced with nixos-generator commands, bud switch(rebuild? idk bud syntax) should be replaced with deploy or nixos-rebuild.

[rummik]

Some additional notes for the documentation overhaul:

One thing that tripped me up for a bit is Digga sets users.mutableUsers = false, so that would be nice to have documented.

This also interacts with the NixOS documentation for users.users.<name>.passwordFile being a bit misleading, since it suggests you should follow the documentation for chpasswd -e, which indicates that you should prefix password lines with a username, rather than it expecting a file containing the value that would be supplied to hashedPassword (ex: mkpasswd -m sha-512, etc)

tl;dr: It took me forever to realize I should use mkpasswd -m sha-512 > password-file 🤦🏻‍♀️