Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add quickstart guides #418

Closed
wants to merge 5 commits into from
Closed

Conversation

milibopp
Copy link
Contributor

I have converted this quickstart guide into a PR now to make it easier to bikeshed.

pinging @domenkozar, as you had some thoughts on guides/tutorials to be added to the site, too?

@domenkozar
Copy link
Member

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

@milibopp
Copy link
Contributor Author

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

@domenkozar
Copy link
Member

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

@garbas
Copy link
Member

garbas commented May 2, 2020

@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.

❤️

@nixos-discourse
Copy link

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

Copy link
Member

@FRidh FRidh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

<pre class="code">
{ pkgs ? import &lt;nixpkgs&gt; {} }:

pkgs.mkShell {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mkShell is a development shell and will run setup hooks which, depending on your use case, you want or not. Because of that reason it should be avoided unless necessary. This is essentially also the nix run versus nix-shell thing. If you just want an environment with several packages, use a plain list.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I don't think I can follow you entirely. I interpret "use a plain list" as this:

{ pkgs ? import <nixpkgs> {} }:

[
  pkgs.which
  pkgs.htop
]

But Nix does not accept that code as a shell.nix. Clearly I am missing something…

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, you are right. It won't work because nix-shell needs to set up an environment. That is unfortunate so I suppose what you have can stay then as the preferred solution. How happy I am with nix run :)

guides/quickstart.tt Outdated Show resolved Hide resolved
guides/quickstart.tt Outdated Show resolved Hide resolved
guides/quickstart.tt Outdated Show resolved Hide resolved
guides/quickstart.tt Outdated Show resolved Hide resolved
@garbas
Copy link
Member

garbas commented May 2, 2020

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.

@domenkozar
Copy link
Member

domenkozar commented May 9, 2020

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)

@milibopp
Copy link
Contributor Author

@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.

@FRidh
Copy link
Member

FRidh commented May 10, 2020

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.

@domenkozar
Copy link
Member

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.

@FRidh
Copy link
Member

FRidh commented May 10, 2020

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

@garbas
Copy link
Member

garbas commented May 11, 2020

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.

@domenkozar
Copy link
Member

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? :)

@garbas
Copy link
Member

garbas commented May 11, 2020

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.

@domenkozar
Copy link
Member

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?

@garbas
Copy link
Member

garbas commented May 11, 2020

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.

@domenkozar
Copy link
Member

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 :)

@milibopp
Copy link
Contributor Author

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.

@edolstra
Copy link
Member

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)?

@FRidh
Copy link
Member

FRidh commented May 11, 2020

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.

@garbas
Copy link
Member

garbas commented May 11, 2020

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.

@domenkozar
Copy link
Member

domenkozar commented May 11, 2020

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

@grahamc
Copy link
Member

grahamc commented May 11, 2020

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

@milibopp milibopp force-pushed the quickstart-guide branch from cb8250a to 59e1423 Compare May 11, 2020 12:35
@milibopp
Copy link
Contributor Author

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

@garbas
Copy link
Member

garbas commented May 11, 2020

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

@milibopp
Copy link
Contributor Author

milibopp commented May 11, 2020

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

@milibopp milibopp force-pushed the quickstart-guide branch from bd0b8c6 to 59e1423 Compare May 11, 2020 13:00
@milibopp
Copy link
Contributor Author

Opened #422 to fix the CI issue.

@milibopp milibopp force-pushed the quickstart-guide branch from 59e1423 to 71413bd Compare May 11, 2020 15:51
@milibopp milibopp changed the title Add quickstart guide Add quickstart guides May 11, 2020
This was referenced May 13, 2020
@garbas
Copy link
Member

garbas commented May 13, 2020

@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)

@domenkozar
Copy link
Member

domenkozar commented May 18, 2020

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.

@domenkozar
Copy link
Member

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

@domenkozar
Copy link
Member

ad hoc developer environments NixOS/nix.dev#18

@milibopp
Copy link
Contributor Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants