search

NixOS / nixos-homepage

Sources for nixos.org
https://nixos.org
311 stars 318 forks source link

Provide an overview + comparison of what nixos, nix, nixpkgs, etc are #734

Open ghost opened 3 years ago

ghost commented 3 years ago

As a newcomer, it's not easy to navigate the homepage and find out what everything is and what they're comparable to.

Problems

1. The landing page

The first thing a new user sees when visiting https://nixos.org is image

Reproducible builds and deployments.

Nix is a tool that takes a unique approach to package management and system configuration. Learn how to make reproducible, declarative and reliable systems.

There's no mention of what NixOS is.

2. nix definition

The above definition says nix is a tool, but I've been corrected by nixxers when saying "nix, the package manager" with "it's a build tool". No idea if that's the consensus, but it's confusing.

Nix is a purely functional package manager

Nix manual

This manual describes how to install, use and extend NixOS, a Linux distribution based on the purely functional package management system Nix

NixOS manual

3. Declarative package installation with nix

It's not explained whether this pertains to NixOS, which seems to be the declarative part of all this (again, newcomer here and still learning), and not nix.

nix-env documentation for installing packages first starts imperatively and then starts explaining profiles. Now, I don't know why this is, but since the selling point of nix seems to be "reproducible, declarative and reliable systems", it's a little jarring to start off with "run nix-env -i subversion to install subversion" instead of "echo "pkgs = [ subversion ]" > profile && nix-env -p profile to install subversion into ....".

4. What are the tools conceptually?

As mentioned above it's not clear what NixOS, nix, nixpkgs, expressions, and all the other things are. There's no easy overview explaining:

The documentation dives in somewhere in the middle goes deep into the subject matter with minimal definitions, mentions a few high level operations and then goes into the deep end again. Maybe it's a style of writing, a preference, a different philosophy, no idea, but it doesn't rub me the right way. Different strokes for different folks, no idea.

Proposed improvements

Landing page

The landing page for NixOS should mention nix very sparsely. For example

NixOS is a linux distribution built on top of a set of tools that allow declarative management and configuration of the system.

Furthermore it's possible to run multiple versions and configurations of services together, as well as easily switch between them.

Example uses are: ...

Documentation

As mentioned in #4 first a good overview would be tremendously helpful e.g:

That can be followed by a nice visual overview (image or ascii art, whatever), then a comparison of the tools e.g

nix component comparable component
nixos arch,debian,opensuse,redhat
nix-env apt,dnf,yum
nixos-rebuild ansible-playbook,salt
/etc/nix/configuration.nix playbook.yml (ansible),top.sls (salt)

And finally a link to https://nixos.org/learn.html

Just to repeat myself again, I'm a newcomer trying to understand what this all is so probably a lot of what I wrote is wrong.

Raikiri commented 2 years ago

I summarized a very similar issue here https://github.com/NixOS/nixos-homepage/issues/828

To me it looks like the user-facing page is currently trying to sell Nix infrastructure to a DevOps engineer who's already using it anyway. And if you're not a DevOps engineer who's already using Nix, you fall under the impression that you're watching an advertisement for a product that clearly has nothing to do with you.

ghost commented 2 years ago

Thanks @Raikiri . Your issue is very similar to mine. Even as a developer, NixOS is not easy to use. There are constant developments that aren't documented or summarized for layfolk and the homepage is very uninviting for someone who isn't already a nix or NixOS user.

I would start writing a top down overview, but I have no idea where to put it. I'm not a nix expert, nor do I have anything to do with web design. The lack of feedback from maintainers and experienced users is a little discouraging too.

It would be great to have an official feedback survey on the website ,or a link to a thread where users could write down what they don't understand or how the homepage could be improved. Right now it seems like they live in their own bubble where newcomers have to climb a steep hill to get into.

fricklerhandwerk commented 2 years ago

Possibly relevant:

Raikiri commented 2 years ago

@fricklerhandwerk I'd love to have either of those functions and I'm willing to contribute to improving the documentation but unfortunately I'm falling into this eternal conundrum where I want to help but I'm knowledgeable enough about good practices, and people who are knowledgeable enough, have better stuff to do.

Nevertheless, both of those functions seem like they'd be a huge improvement.

fricklerhandwerk commented 2 years ago

@Raikiri finding entry points to contributing is a permanent problem in the open source space. It takes additional effort for maintainers to provide affordances for new contributors, such as triaging for suitable issues, providing appropriate learning material, or just taking time to hold someone's hand.

If you want to tackle something that bothers you and feels approachable in terms of scope, I would recommend to directly ask for pointers on the respective GitHub issue, or open a thread on NixOS Discourse. Keep in mind to ask informed questions, as that helps everyone else to help you, and also keeps a paper trail to pick up from.

Many things simply have not been written down properly because no one asked yet. Good questions are part of the documentation.

Raikiri commented 2 years ago

@fricklerhandwerk in my view, it's currently pointless to advertise NixOS to a person without a previous experience of installing a manual-maintenance distro such as arch or gentoo. But that's a pretty substantial audience and it can be expanded to more casual users when the distro becomes more casual user-friendly.

My rationale of why it requires potential users to at least have experience with some "technical" distros is because NixOS specifically addresses problems that become apparent to anybody who tried to manage packages imperatively themselves. Like, an average ubuntu user will probably not even be aware that these problems exist, and it's just too early advertise nix currently as an alternative to an average windows user.

In my opinion, this provides a ballpark vision on the low bar of the knowledge level of an average NixOS's new user. And I might say that the current advertisement material requires way more specific expertise (DevOps expertise to be precise) to get excited. Say, an average arch user will not even understand why they want reproducible builds at all, because they've lived all their arch life perfectly fine without them.

fricklerhandwerk commented 2 years ago

Sounds very reasonable. I'd be happy to see you elaborate how and where to address this kind of audience. As said, Discourse may be a good place to start, short of making pull requests.

nixos-discourse commented 2 years ago

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/actionable-short-term-improvements-to-the-website/18748/1

nixos-discourse commented 2 years ago

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/landing-page-is-completely-unclear-for-new-users/22990/3

nixos-discourse commented 1 year ago

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/benefit-layers-on-the-nix-homepage/30432/5

nixos-discourse commented 1 year ago

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/where-did-you-get-stuck-in-the-nix-ecosystem-tell-me-your-story/31415/39