NixOS / NixOS/nix.dev

Expand and improve the Module System tutorial

Open
#966 5 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

site tracking
Dominant language
Nix
Stars
4k
Forks
339
Avg merge
2d 11h
Merged PRs (30d)
7

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the current module system deep dive and the first lesson at nixos-modules.nix.みんな/lessons/a-basic-module/lesson/. Compare the workshop lessons with the existing tutorial and review how the external site verifies snippets and results at build time. Done means the first lesson and, if accepted, the remaining lessons are migrated while the deep dive is refocused to remove overlap.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.