Still no idea what this does and what to expect after reading readme.md

[Raikiri]

Expected Behavior

I expect to get some understanding what this project is about after reading its readme

Current Behavior

Still no idea what I'm looking at. I got even more lost after looking at https://github.com/divnix/digga/tree/main/examples

Possible Solution

Please can we add more explanations on different levels of what this project is trying to accomplish? First, an explanation for a person who has never heard of what nix is, in very broad strokes. Then an explanation for a person familiar with nix but who has no idea what flakes are. And only then the current explanation for a person who's already "in the loop".

One particular thing that I think is missing is an explanation: is this project supposed to replace manual configuration.nix/home-manager or provide a more convenient way of managing them? Or it's something entirely different?

Steps to Reproduce

1. Read readme.mb
2. Experience feeling lost

Context

I consider myself to be a huge admirer of Nix/NixOS philosophy but only a novice user. I have gone through the official documentation on how to install it, then I read a bunch of info on how to setup configuration.nix, loved it. Then I randomly found home-manager, loved the concept, started using it.

But then I discovered there is this thing now called flakes and there was this gigantic drama that unfolded around it https://discourse.nixos.org/t/nix-2-4-and-what-s-next/16257/18 and then I go looking for information on how/why I can use flakes, find this repo that looks like it's exactly relevant because it seems to be directly UX-facing, yet I have absolutely no clue where to even start.

Some really simple minimal examples can really help here, in my opinion. Like, actually simple, not simple for a person who has created this thing. As well as a really high-level overview of what the goals are for an end-user and its relationship with the rest of the nix environment.

[montchr]

Hi @Raikiri,

Thanks for your valuable and candid feedback. I totally understand and empathize with your feeling of being lost when approaching this project. I've been there before!

I first saw the project referenced by Henrik Lissner's dotfiles as "an overengineered config to scare off beginners". It scared me, but it also seemed like the closest thing available to a "definitive" guide to best practices for system configurations with flakes, especially at a time when flakes seemed straight-up controversial.

One particular thing that I think is missing is an explanation: is this project supposed to replace manual configuration.nix/home-manager or provide a more convenient way of managing them? Or it's something entirely different?

To answer your specific question:

Flakes can already replace a configuration.nix file on their own:

https://nixos.wiki/wiki/Flakes#Using_nix_flakes_with_NixOS

Digga provides a layer of abstraction over NixOS, home-manager, and soon nix-darwin. It leans heavily on https://github.com/gytis-ivaskevicius/flake-utils-plus and home-manager. I think "provide a more convenient way of managing them" is the goal here… but clearly, that hasn't turned out so well since that isn't entirely clear!

While I think we've made a decent amount of improvements to Digga's API, the documentation has always been its greatest weak point. And, unfortunately, I think the same can be said of Nix/NixOS in general – which is exactly why we need strong-but-flexible reference points to learn from. One of my personal goals for working on this project in the near future is to help grow its documentation, which definitely needs a rework. Even in lieu of extensive tutorial-like guides, I'd like to add a bunch more inline comments too.

Personally, if I'm setting up a new system from scratch from the ISO provided on nixos.org, I still tend to run through the initial steps in the installation manual to generate the hardware-configuration.nix file and provide a simple starting place.

I think a guide for setting up a flakes/Digga-based NixOS configuration starting from the "vanilla" NixOS installation medium would be pretty helpful. I think there are some docs here about creating a custom ISO image, but I don't think they're up to date, and that's not particularly helpful if you're newly starting with flakes without much of a point of reference.

[Raikiri]

@montchr it's funny that you mention best practices for system configurations with flakes, especially at a time when flakes seemed straight-up controversial, as if it's obvious to me that I know they were a controversial subject and now they're not? I spent a whole day of digging through various blogposts and github depths just to understand what flakes are designed to do and I still have literally 0 clue what people think of them and what I'm expected to feel about them.

I'm not saying it as a critique, but rather as a request to feel free to add opinionated sections into various descriptions. A section with some minimal introduction like this will really help:

Have you already experienced the joy of using nix and nix os with their declarative configuration?
Have you already discovered home-manager that helps you manage your home
 directory in the same declarative fashion. Then you might have noticed that managing 
them separately can feel awkward. The goal of this project is to provide a common abstraction over them and to...

Also maybe add a section somewhere that "This project embraces the newly introduced to nixos concept of flakes to allow standartized way to manage dependencies. We believe that flakes is the right way to go and produce a flake configuration file as a result", or something like this, I clearly have no idea what I'm talking about here.

Basically the idea is that the description is not only supposed to add why its potential user wants it, but also a way how somebody else can easily find that they're straight up on the wrong page. Like, if my grandpa reads "have your already used nix?" he should be able to straight up decide : "nope, not for me" and move on. Currently this would be very unclear to him, because the first thing the readme does is it explains the name and then moves on to explain what it does without providing any introduction who and why might want it.

While I think we've made a decent amount of improvements to Digga's API, the documentation has always been its greatest weak point. And, unfortunately, I think the same can be said of Nix/NixOS in general
I completely agree. The whole nix infrastructure feels like a crazy genius-level creation by its authors for themselves. And whenever they want to advertise it, it feels like they try to advertise it to themselves rather than to a person who has no clue what they're looking at.

Obviously I welcome your plans to work on documentation. However, I think a clear guide on how to configure a vanilla NixOS would be much more useful than a preconfigured ISO, because the whole point of a configuration utility is to show how easy it is to configure stuff with it. And if one must download a preconfigured ISO, it's clearly not easy enough.

[nathanscully]

I've gone through the same journey @Raikiri, you aren't alone. I am still trying to cobble together a working config and slowly build an understanding of Nix - I've spent a lot of time trying to unpick different peoples configs to feel like I am just scratching the surface.
I'd thought I'd link an excellent series by Xe here: https://christine.website/blog/series/nix-flakes that might help if you haven't seen it. It follows a similar start from scratch approach but is focused on a service rather than the OS but I think the gradual introduction of terms, technology and code samples is well executed. It could be a source of inspiration for the Doc overhaul mentioned in #456.
A suggestion is that the Digga docs should focus on "what code can you remove". From what I can tell it provides a number of sensible APIs and concepts (suites, profiles etc) that simplify and keep a healthy separation of code within a Nix config. I'd focus on small building blocks around these APIs than the devos example - its doing too much and overwhelming unless you already have a good grasp of Nix. I think there is a place for it to demonstrate how it can all come together but thats the final step.