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

Expand and improve the Module System tutorial #966

Open
djacu opened this issue Apr 19, 2024 · 5 comments
Open

Expand and improve the Module System tutorial #966

djacu opened this issue Apr 19, 2024 · 5 comments
Labels
site Improvements to the site infrastructure or content presentation tracking A stopgap for issue dependencies

Comments

@djacu
Copy link
Member

djacu commented Apr 19, 2024

Hey @NixOS/documentation-team

Observations
I've already chatted with @fricklerhandwerk and @infinisil about improving the module system deep dive article. I've written quite a bit of material for a workshop I gave at NixCon NA this year and I it is worth migrating to nix.dev.

Problem
The current module system deep dive is:

  • long for a single lesson
  • hard to maintain (changing a bit of code upstream requires many changes because of the use of code diffs)
  • uses external APIs

Approaches
As mentioned, I presented a workshop on the module system. To prepare for that, I created my own set of lessons and a website to host them (https://nixos-modules.nix.みんな/).

Each lesson is:

  • minimal: Only 1 - 2 new concepts are introduced in each lesson
  • hermetic: The example code in each lesson is stand-alone and does not require you to continue from another lesson
  • verified to work: The infra for my site injects the code snippets and the output/results of each example into the lesson markdown at build time. If the lesson doesn't work, the site doesn't build. :)
  • isolated from externals: All of the lessons use only Nix expressions and a small few use simple packages from nixpkgs. No external APIs or knowledge are necessary to read through the lessons. This limits the amount of new knowledge that is being shown to the user in each lesson and helps lower their mental load.

My plan for migration is as follows:

  1. We agree this is a good idea!
  2. Migrate the first lesson (https://nixos-modules.nix.みんな/lessons/a-basic-module/lesson/)
  3. We migrate the infra so that lessons are verified to work at build time. If this is something we want to take on.
  4. Migrate the remaining lessons.
  5. Modify the current deep dive. There is a lot of overlap between my lessons and the deep dive. If these lessons are migrated, we can cut back on the earlier sections of the deep dive and focus on the unique aspects of it.
  6. Add more lessons. What I have is not comprehensive and is just sufficient to get someone started on the module system. There is much more to explain and document.

Willing to help?
Yes

Priorities

Add 👍 to issues you find important.

@djacu djacu added the site Improvements to the site infrastructure or content presentation label Apr 19, 2024
@nixos-discourse
Copy link

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

https://discourse.nixos.org/t/2024-04-25-documentation-team-meeting-notes-122/44080/1

@autra
Copy link

autra commented Apr 26, 2024

Sounds really nice! I had started to rewrite the "deep dive" tuto using open services (osm mainly) but frankly, I'm not sure it is a good idea: the deep dive might be funny to follow and imo works well in a workshop, but it's not a very real packaging use case. Also I'm quite new in the nix world, and I suspect part of it are outdated (but can't really judge for sure).

I think that from a newcomer perspective (I've only started learning nix in 2024), there is a gap just before the "packaging existing software" page on nix.dev, which some of your first lessons could very well fill even before the "deep dive" page.

Add more lessons. What I have is not comprehensive and is just sufficient to get someone started on the module system. There is much more to explain and document.

Especially, nixpkgs and the library it provides is still a lot more unknown to me that nix (the language) itself. It would be nice to have some lessons about it

Anyway, if you need a guinea pig for your pull requests, don't hesitate to ping me :-)

@fricklerhandwerk
Copy link
Collaborator

Sorry for not commenting earlier, my notification queue is too long.

The infra aspect is really good and generally desirable, especially if it's somewhat transparent how it works and thus easy to maintain or create new samples.

Concerning the migration or merging of contents, I think it's a very good idea because the deep dive has a couple structural issues. I'm just a bit skeptical how exactly to approach such a lengthy and review-intensive process such that we won't have two construction sites next to each other for an indefinite amount of time.

One of my primary goals is for nix.dev to be small but authoritative (in the sense of "exactly one, working solution to each problem"), which kind of precludes showing essentially equivalent alternatives. I know, we're not very far with that. @djacu maybe you drop into one of the office hours and we figure out how to move forward in a high bandwidth conversation?

@djacu
Copy link
Member Author

djacu commented May 13, 2024

@fricklerhandwerk my idea for merging was to leave the current deep dive alone until we had a decent amount of content migrated. There are definitely a lot more details to work out so I'll try to be at the Thursday meeting. That's what you meant by office hours, right?

@nixos-discourse
Copy link

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

https://discourse.nixos.org/t/2024-05-16-documentation-team-meeting-notes-128/45537/1

@fricklerhandwerk fricklerhandwerk added the tracking A stopgap for issue dependencies label Jun 12, 2024
@fricklerhandwerk fricklerhandwerk changed the title Expand and Improve Module Article Expand and improve the Module System tutorial Jun 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
site Improvements to the site infrastructure or content presentation tracking A stopgap for issue dependencies
Projects
Status: No status
Development

No branches or pull requests

4 participants