Description
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.
- Graphic of the control flow #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.