I'm afraid that quickstart will become an catchall, I think it would be better to have tutorials clearly define one goal (instead of multiple).

Note that there's already quickstart in the manual: https://nixos.org/nix/manual/#chap-quick-start

So I'd rather split this into two tutorials:

• setting up development environments
• building docker images

I see your point. Perhaps to clarify: my goal here is to get newcomers started with Nix quickly, so they can see value in it without getting confused. Hence, I am ignoring the manual, as I do not believe it is very effective at that.

So in any case, there are obvious redundancies with the manual. When I split this up, they will become more obvious on the learn page.

As it stands, I would make the following changes:

• split into three pages: install, first shell, dev environment
• link them from /learn.html
• cross-link them with some kind of navigation
• to reduce the scope a bit drop Docker images for now → future PR

Yeah I think even if we have separate tutorials, the intention to show off the value is still there.

@domenkozar great idea to split it up in multiple guides.
@aepsil0n I was just about to propose "How to install Nix" guide, but I see you already split them into few (install, dev environment, building docker images)

Is wasn't mentioned anywhere but you are doing guides around Nix, which I think is exactly what we need first. NixOS guides can wait for now or maybe somebody else can tackle that alongside.

I would just like to remind you - as I try to remind myself every time:

• Do small steps, don't aim to be perfect in order to merge, just make it better then current situation.
• We can always improve in following PRs, it is more important that you keep your energy for contributing high.

❤️

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

https://discourse.nixos.org/t/marketing-team-meeting-minutes-4/6988/1

I am definitely for having guides, but I don't think they should be part of the website code because its a substantial topic/part on its own. Instead, we should have them as a separate project. I know, it brings up the discussion again about manual and format. But it is important that we have a clear place for this and the website is not it.

As said in the meeting, website we'll be the initial place and then we can extract them in out. I know this is not your intention, but please don't kill the energy around this effort. What we need is content and then we can start discussing where and how to package it. Clearly using HTML - as it is done now - is not the tool that will be used in the long run, but this avoids us from having the which-documentation-tool-to-use discussion and focus work on content. And don't get me wrong that discussion is important to have, and there is an RFC dedicated to it, we'll just wait and see what comes out of the discussion, until then since the website needs guides/tutorials we'll just write them in HTML.

Also sorry for jumping on you with all this words. I'm just protective of the plan we have in marketing team. I want early results showing each week and having an new repo means more discussions that are not needed at this point and are already in progress in rfc process.

As said in the meeting, website we'll be the initial place and then we can extract them in out. I know this is not your intention, but please don't kill the energy around this effort.

I actually think @FRidh is trying to save energy. Having it all in HTML is going to be huge pain to maintain it.

We don't need to have a wider discussion and just do it for now. HTML is as random choice as something else :)

I don't see a problem setting up restructured text on readthedocs.org, but it's also up to @aepsil0n to say if he's willing to convert to RST.

(bringing this up as nixops is already converting to RST)

@garbas thanks for caring about preserving the momentum. It is important to stay focussed.

I do not necessarily mind rewriting this in RST at all, in fact I prototyped this in Markdown before converting to HTML.

However, it is obvious that the target here is a bit fuzzy. Before moving on with the implementation I would like to get a rough consensus on design and architecture. In summary, I think these are the main points to decide on:

1. One-page quickstart guide vs. separate pages for each topic
2. Markup language: HTML+TT vs RST (any other contenders?)
3. On nixos.org vs. making a separate guide site

Anything else?

My personal opinion: separate pages make total sense. As mentioned before, I would likely add a navigation, too. (I am thinking of the Rust book as a pretty good example to follow in terms of how the content is organized.)

On markup language and moving things off the site: I agree the HTML+TT situation is not really great in the long run. But I also believe changing the templating system is out of scope here, and I certainly did not think of uprooting the architecture to be one of my first contributions to this site ;) Also be mindful of the overhead of maintaining a separate second site. Sure we can keep it minimal, but there is still extra work involved.

Do you see a non-technical reason for moving off the site? Because I definitely think that there should be official guides on the website to provide new users with direction, until they learn to navigate the ecosystem on their own. Hence this PR. If we want to use different technology, that's a bigger refactoring that should be done independently and should not block on-going content work (especially not before such a refactoring has actually started). But i am sensing some urgency to get to that refactoring, so perhaps we should tackle this discussion rather soon.

Do you see a non-technical reason for moving off the site?

Peer review. Tutorials are distinctively different content from website code and thus attract different users/reviewers. This is my main motivation why it best be moved elsewhere.

However, it is obvious that the target here is a bit fuzzy. Before moving on with the implementation I would like to get a rough consensus on design and architecture. In summary, I think these are the main points to decide on:

1. One-page quickstart guide vs. separate pages for each topic

I'd start with each tutorial as a separate page.

2. Markup language: HTML+TT vs RST (any other contenders?)

RST

3. On nixos.org vs. making a separate guide site

Separate site, as @FRidh pointed out.

All of this is trivial to setup, if you'd like I can do it.

(of course I have to refer here to https://fridh.github.io/nix-tutorials/ but not saying it should replace it)

1. One-page quickstart guide vs. separate pages for each topic

Separate.

2. Markup language: HTML+TT vs RST (any other contenders?)

HTML+TT ... we are not changing any tooling at this point. I don't like it as much as you do, but I don't want to have this discussion. There is an RFC where this discussion takes place. for now we are sticking to what we already use.

3. On nixos.org vs. making a separate guide site

As I said above, we will start by having this content under nixos-homepage and once documentation team is formed or we have to much content to list them on the learn page. I hope that we will reach this point, but until then keep it simple and lets just focus on the content.

HTML+TT ... we are not changing any tooling at this point. I don't like it as much as you do, but I don't want to have this discussion. There is an RFC where this discussion takes place. for now we are sticking to what we already use.

Are we getting death by committee treatment? :)

HTML+TT ... we are not changing any tooling at this point. I don't like it as much as you do, but I don't want to have this discussion. There is an RFC where this discussion takes place. for now we are sticking to what we already use.

Are we getting death by committee treatment? :)

Just avoiding death by committee.

So far everyone is on board except you @garbas so we have to decide about governance here, are you making final calls or the team?

Well then please bring this up on the meeting and involve others into discussion so that it would be fair. Having just a few of us looking at this PR doesn't really give justice to any sort of discussion. And since you are asking for decision to be made we also would need to include everybody in NixOS/rfcs#64

Governance is clear here. Go via the RFC which is already taking place. I think this is a touchy subject for many. I want to avoid any discussion and just get content on the website without changing tools.

Oh sorry, @aepsil0n is also on the HTML+TT train.

I don't think we need to have RFC discussion in the marketing team, but maintaining documentation in nixos.org repository with HTML+TT is a really bad default.

Since this is @aepsil0n's PR I'll refrain from further comments and let him work in peace :)

I would like to remind everyone that written communication on a issue board like this can easily get a bit out of hand, as nuance is easily lost. I have put an item on the agenda for the marketing team on Wednesday to discuss this face-to-face, which hopefully lets us address this issue better.

Summarizing…

on 1. we have a consensus here that the guide sections should be split into separate pages.
on 2. & 3. we are split.

To be honest I am not entirely sure how to proceed. By default I am inclined not to change technology and just add the content following @garbas' suggestion.

@domenkozar yes, I guess I am on the HTML+TT train. I don't like the tech either, but it is more practical to get work on the content done.

One of the main complaints that people have about Nix documentation is that it's very scattered: there is a Nix manual, a Nixpkgs manual, a NixOS manual, Nix pills, the wiki... This adds yet another source of documentation. Maybe it's better to add this to the Nix manual (replacing the existing quick start section)?

One of the main complaints that people have about Nix documentation is that it's very scattered

That is a good point to consider. At the same time, I think it is important that we realize that the scope of Nix(pkgs) is huge. In NixOS/nixpkgs#87094 a remark was made that the introduction material there (for Python) was not describing certain parts, which the author (me) assumed to be more belonging in a Nix tutorial.

Often people request practical tutorials without much description beforehand. What is the scope of these tutorials? To form a place to gather many tutorials? Or is it more intended to make people interested in Nix? I suppose it is the latter given the initiative comes from the Marketing team. In that case I suppose its best if the tutorials are kept somewhere else (close to the source) and those that are intended for here would be linked to or included somehow, to avoid the risk of getting out of date.

One of the main complaints that people have about Nix documentation is that it's very scattered: there is a Nix manual, a Nixpkgs manual, a NixOS manual, Nix pills, the wiki... This adds yet another source of documentation. Maybe it's better to add this to the Nix manual (replacing the existing quick start section)?

From a visitor perspective this doesn't add a new place where you find documentation, eg. there is Learn button and you can find stuff which you are interested in. From contribution perspective, yes there is a new 4th place where we keep things (temporarily, until we figure out where to put them and in which format and who is going to govern them).

This are the reasons why I think we should keep guides/tutorials outside current manuals:

1. What newcomers clearly have a problem is that they don't know about the difference between this 3 projects. Some even discover nixpkgs manual months after they learned Nix.

2. Current structure of manuals, being one page, is intimidating for newcomers. I saw many get lost or overwhelmed.

3. Even if newcomers knows about the 3 manuals and is not intimidated or lost, it is hard to know in which manual to search. Even I have sometimes problems with this.

4. The guides/tutorials I have in mind could sometimes fit in 2 or even all 3 manuals. And some other ones I would never include it.

Do I think this is how documentation is going to be done going forward? No. It should be in one place with tooling we agree upon, maybe even a team should be formed that will take care of it.

But - I think - proposed solution will solve the problem until community agrees on tooling, format, place, governance, ... and make it easier for newcomers to learn Nix/NixOS.

After RST (nixops, python), markdown (parts of manual), docbook (manuals), HTML+TT is going to be yet another format to write documentation in.

I don't buy the argument that it will be converted at some point, who is going to do that work? Why not use some of the existing tooling at least? If we're picking a bad default, starting with another fresh format and place is really diverging the community even further.

I agree it would be much better to have a format defined, but we can just link from Learn page to wherever and pick a saner default. I think picking RST over markdown and docbook would be since it has a high chance of being the outcome of that RFC, but that's pure speculation. We know upfront that HTML+TT won't be a winner.

I also agree putting tutorials in a manual is a documentation anti-pattern, so starting with https://nixops.readthedocs.io/en/latest/ is quite easy (literally a few min job for someone familiar with sphinx).

Plus once we have documentation team, handing over is going to be easier

(fwiw, NixOps chose RST because it is standard in the Python ecosystem, and for no other reason.)

Anyone know what's up with the update.sh script in the CI pipeline?

@aepsil0n I can look at it, but later this evening if you wont fix it already.

Got it, was related to NixOS/nix#3551. I will open another PR, as this has nothing to do with the guides.

Opened #422 to fix the CI issue.

@aepsil0n In order to get a preview for your changes you in the comments you need to be working from a branch on this repository. I noticed you are not part of the @NixOS/nixos-homepage group and I added you to it which should give you permission to push quickstart-guide branch to this repository and get preview.

I would suggest to open this PR and open a new one. This could also serve as a nice way to restart the discussion on the content of quickstart guides. I just did something similar with landing page PR (#425)

Based on the long discussion I decided to do some work rather than just talk.

I've set up https://nix.dev/ (currently source lives at https://github.com/domenkozar/nix.dev) with tutorials from this PR.

This has everything set up for making it easy to write documentation:

• preview PRs via netlify
• includes a script to live-reload browser on changes to RST files for development

i'm planning next to open a PR with my suggestions to improve the tutorials further.

Started with installation tutorial: NixOS/nix.dev#12

ad hoc developer environments NixOS/nix.dev#18

I am going to close this issue in favor of the collaboration on https://github.com/domenkozar/nix.dev
Accompanying issues will be opened for integration into https://nixos.org and perhaps further guides.