[okanat]

> I'm used to working in large projects with source-code as the only documentation.

As a software engineer I have an opposing attitude towards this. I work on projects with terrible documentation because somebody pays me to do so or there is a significant potential that I can unlock.

There are significant alternatives to NixOS like bootable containers and OSTree which are more useful and better documented. If Nix project really cares about being competitive and adopt users, they have to document their stuff. They are already going against the grain and ain't nobody has time to put up with their weird language and their subpar documentation.

[Arelius]

> I work on projects with terrible documentation because somebody pays me to do so or there is a significant potential that I can unlock.

I mean, I'd argue there is significant potential, but really, for me it's just easy because I've been doing it for 20 years, and documentation is always fundamentally worse than code in some important ways.

> If Nix project really cares about being competitive and adopt users, they have to document their stuff.

This is one of the good/bad things about OSS.. most users don't provide positive value to the project. So do they really want to adopt users? Shrugs but the project is certainly competitive.

[ofkwidjwus]

> for me it's just easy because I've been doing it for 20 years

C’mon, just drop the “greybeard” act. Nix not having proper documentation is bad practice, period. No ifs buts or howevers, it’s just an objective fact. Good documentation is always (ALWAYS) a net positive, and this is an OS with it’s own unique mindset and way of doing things, good documentation is essential. End of.