Why does "first steps" with NixOS on the main page lead to a dev environment tutorial?

[Raikiri]

Introduce your stance
As a new user, I was looking for information as to how to use the newly installed NixOS (how to configure basic stuff), etc, and naturally went to the NixOS's main page.

Describe the issue
On the main page there's a link to the "learn" page: https://nixos.org/learn.html that conveniently has a "first steps with nix" right after the "install nix" option. But this confusingly leads me to a dev environment setup tutorial which is definitely not going to be my first steps when I'm facing a freshly installed OS. I at least need to configure things such as keyboard layout, desktop environment, etc etc.

Page links
https://nixos.org/learn.html
https://nixos.org/guides/dev-environment.html

Additional context
I understand that setting up a dev environment can potentially be the first step right after installing Nix on an existing linux setup, but I expect the "first steps" on a NixOS webpage to lead to "first steps with NixOS". Or at least I expect the link to be named "dev environment setup with Nix".

• I already created a Pull Request

[fricklerhandwerk]

@garbas fixed by #851

[Rosuavio]

@garbas fixed by #851

@fricklerhandwerk, I don't believe that PR fixes this issue. I don't mean to speak for @Raikiri, but it seems that the issue is that @Raikiri is expecting the "first steps" to be "first steps after installing NixOS". While from the perspectives of experienced users it is clear that the content in the "Learn" page is always referring to Nix and not NixOS, newer users can get confused because they are not expecting Nix to specifically refer to the command line utility and NixOS to specifically refer to the operation system.

Since the "Learn" tab is accessible from the NixOS homepage (any many other pages), I think it's reasonable to expect users to assume that "Learn" refers to Nix, NixOS or both.

Possible solutions for this confusion are

• Rename the "Learn" tab to "Learn nix"
• Split the learn page into a sections labeled "NixOS" (containing NixOS related content) and "Nix" (containing Nix related content)
• Rename the "Learn" tab to "Learn nix" and add a "Learn NixOS" tab with NixOS related content.

[Raikiri]

While I agree that having a more general setup for a development environment is better than having an arbitrarily chosen python environment, it does miss the point though: my first steps on a freshly installed system are definitely not going to be "creating a development environment" at all.

It's going to be questions like: "where are my configs?", "what's the basic examples of the nix config file?", "what do I install as a module and what do I install as a package and why?", "how do I update?", "what should I NOT do?", "how do imperative package management commands that I'm used to, map to nix's declarative paradigm?".

I know people often refer this set of basic questions to the general confusion created by a website that has "nixos" in the domain, but is actually referring to "nix" in its content. However, even when it comes to configuring nix itself, there seem to be lots of really basic "first steps" to learn prior to setting a development environment.

[fricklerhandwerk]

the issue is that @Raikiri is expecting the "first steps" to be "first steps after installing NixOS"

@Rosuavio Yes, right.

newer users can get confused because they are not expecting Nix to specifically refer to the command line utility and NixOS to specifically refer to the operation system.

Fully agree, have myself seen people being confused, and I am working towards improving that. Right now I think the biggest problem is that the front page says NixOS in large letters, while currently the web site is really about Nix and Nixpkgs.

@Rosuavio @Raikiri @Narice As a first step, would it help you if we changed "NixOS" to "Nix" in the headline and page titles? #707 is related.

I concur with the premise of #633 and think we should eventually move what is currently nixos.org to nixpkgs.org (because we already own that domain, although owning nix.org would be ideal) and only reference nixos.org for everything about NixOS. But it is tricky issue and would be a big change, which needs careful consideration.

my first steps on a freshly installed system are definitely not going to be "creating a development environment" at all.

@Raikiri do you mean NixOS by a "freshly installed system"? Right now the web site is supposed to be about Nix, not NixOS. As I already wrote we have to prioritize due to limited resources, and the decision was to focus on software developers, and explicitly not on NixOS users. The debate about a roadmap to coordinate or integrate documentation efforts is still ongoing, and expanding it here would be off topic.

However, even when it comes to configuring nix itself, there seem to be lots of really basic "first steps" to learn prior to setting a development environment.

@Raikiri what are these questions specifically? Maybe I got it wrong, but the ones you listed appear to be about NixOS.

@Rosuavio @Raikiri what do you think about placing a diagram along these lines on one of the pages, and explain the distinction between each component? Ideas on placement and wording? Would be absolutely great if you could directly submit something as a pull request.

flowchart
  Nix --> lang[Nix language]
  Nixpkgs --> lang
  NixOS --> Nix & Nixpkgs

Loading

[fricklerhandwerk]

@Raikiri @Rosuavio Does #891 address this issue? I will hopefully soon replace the NixOS logo graphics with one that only shows "Nix", to further reduce potential for confusion.

I know that nixos.org will then be mostly about Nix and not NixOS. We have an open issue that has to be addressed by the Foundation board and Nix marketing team to have a proper place serving NixOS.

[Raikiri]

@fricklerhandwerk are the changes live already? Because as far as i can tell, all links in the "Learn" category on nixos.org website still lead to nix stuff. "First steps with NixOS" and "Learn how NixOS works" is still nowhere to be found.

I'd argue the current "first steps" article is not even what the majority of nix users expect: they don't expect to use it for development purposes at first, they expect to learn how to do basic things with it such as declaratively installing packages, modules, options -- that sort of stuff.

[fricklerhandwerk]

@Raikiri as of today the Learn page shows Nix instead of NixOS:

That the "First steps with Nix" is titled "Ad hoc developer environments" but is really about, well, just "environments" is surely debatable. Feel free to propose a change.

I suppose @domenkozar originally did that for SEO, and also, as said, we are currently focused on software developers. Hence we try to primarily improve the onboarding experience for Nix.

I agree that the state of affairs is frustrating for NixOS enthusiasts, and would encourage you and everyone interested in fostering NixOS to set up a dedicated web site for NixOS. This obviously requires significant effort and coordination, and apparently no one so far has been able to afford that. Still, if it works out, we can always add official branding and domain names.

[nova-nowiz]

There are two distinct group of users in the Nix/OS community.
Users of the NixOS operating system and users of Nix.

Obviously, there are links between the two.
A person using NixOS will have to use Nix.

I'd argue that the graph proposed by @fricklerhandwerk should go in the other direction.
NixOS build onto the Nix Package Manager and Collection, and they themselves build on the Nix Language.

So the Nix Language is the source.
And here is one learning problem: All our tools uses the Nix Language, but learning the language is actually pretty tough as there are not a lot of resources on it. I don't mean Nix Pills, I mean a terse Nix Language Book and Reference.
The new Nix Manual is already a huge improvement, but is unfortunatly still not sufficient in my opinion.
How to really use the language, starting from no coding experience, or at least standard developer experience, that means, no functional programming knowledge in most cases.
It is a shame that in some ways this community is composed of I would say mostly functional programmers, that is a low overall percentage of the programming community.

A second problem that we have is that there are a lot of abstractions to learn and understand.
Modules, options, flakes, nix shells... And the abstractions used for one part of the community to an other are not the same, it depends widly on what you do with the Nix Language.
So building tutorials for each community is essential as the first steps will not be the same.

Thirdly, it is indeed better indeed to have the main website be about Nix, and I would say more precisely, Nix, the Package Manager. It is the cornerstone of every other tool and the reason why nixpkgs and the Nix Language exist.
As such, it is a great way of entry as everything else can be introduced in a resonable fashion.
An alternative to the "Nix" in the title would be "Nix/OS". I began using this after thinking that writing "Nix / NixOS" everywhere was very silly, and it seems appropiate to reconcile both parts of the community, without having to change the domain of the site.

Finally, building a community made website is a great thing, but having official documentation is a lot better.
I know and understand that resources are limited, but using a tool without having a good way of learning it is a hard journey.

[fricklerhandwerk]

All our tools uses the Nix Language, but learning the language is actually pretty tough as there are not a lot of resources on it.

@Narice My Nix language tutorial is waiting for reviews. I'd be happy to read your feedback.

[nova-nowiz]

From what I can tell @fricklerhandwerk, your tutorial is awesome.
I din't read through the worked examples, but outside of that, that is a fantastic starter guide.
It doesn't cover everything that you need for writing in Nix, but it says so clearly and points people to resources for learning more: awesome.

[nova-nowiz]

I just saw that your change is on nix.dev instead of being here, I'm not too familiar with the way this website is built, does it refer directly to the articles on nix.dev?
If so, why is nix.dev considered unofficial?

[fricklerhandwerk]

Yes, nix.dev articles are included here, and unfortunately still without attribution. I'd be happy if someone took the time to at least add a note and a link to the original, for example here, and would help getting the change merged.

I opened a PR to make nix.dev official, but there are still a few things in the way I can't do much about (see the comments there).

[nixos-discourse]

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

https://discourse.nixos.org/t/usability-study-session-2/21400/1