• Stars
    star
    183
  • Rank 210,154 (Top 5 %)
  • Language
  • License
    Other
  • Created over 2 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Nix documentation – centralized community online learning resource for Nix

The Nix Book

Warning This repository may eventually disappear.

The Nix documentation team now works on nix.dev towards the vision outlined here.

A vision for the journey into Nix, nixpkgs, and NixOS

This book is supposed to fit between first impressions on the Nix web site and the reference manuals for Nix, Nixpkgs, NixOS.

flowchart
  subgraph homepage
	  core --> explore
		get-started --> learn
		explore --> |details| how-nix-works
	  subgraph front-page[front page]
			subgraph core[core features]
				same[always working environment, everywhere]
				polyglot[many programming languages]
				deploy[configure, build, deploy]
				rollbacks[roll back any time]
				community[global community]
			end
			examples
			get-started[get started]
		end
		subgraph explore
			complete[complete dependencies]
			reproducible[reproducible builds]
			correct[correct deployment]
			multiple[multiple versions]
			atomic[atomic upgrades]
			agnostic[many programming languages]
			caching[transparent caching]
			remote[remote builds]
			nixpkgs[community package collection]
			nixexpr[purely functional configuration language]
		end
		subgraph learn
			install
			first-steps[first steps]
			how-nix-works[how nix works]
	  end
  end
	first-steps --> book --> manuals --> source
	book --> discussion
	subgraph book[The Nix Book]
		direction TB
		build --> imperative-pkgs & declarative-pkgs
		declarative-pkgs --> writing --> declarative-config & dev & nixpkgs-learn
		subgraph build[run software]
			direction LR
			find-pkg[find packages]
			run[run a program]
			shell[set up temporary environment]
		end
		subgraph imperative-pkgs[imperative package management]
			direction LR
			install-profile[install]
			update
			rollback
			pin-packages[pin packages]
		end
		subgraph declarative-pkgs[declarative package management]
			direction LR
			decl-env[reproducible environment]
			compose[compose packages]
			adapt[adapt packages]
			pin-deps[pin dependencies]
			gc[garbage collection]
		end
		subgraph nixpkgs-learn[package collection]
			direction LR
			modify[modify existing package]
			newpkg[create new package]
			contribute-nixpkgs[contribute to nixpkgs]
		end
		subgraph declarative-config[declarative configuration management]
			direction LR
			user-env[user environments]
			os[operating system distribution]
			services[service management]
		end
		subgraph writing[configuration language]
			syntax
			functions
			attrsets[attribute sets]
			debugging
			library
			tools[tool support]
		end
		subgraph dev[software development]
			direction LR
			lang-ecosystems[language ecosystems]
			caching
			deployment
			ci[continuous integration]
			distributed[distributed builds]
			cross-compilation
			bundling[bundling build results]
		end
	end
	subgraph discussion
		RFCs
		pr[pull requests]
		issues
		Discourse
	end
	subgraph manuals
		subgraph man-nix[Nix]
			cmd[command line interface]
		lang[expression language]
			config[configuration]
			architecture
		end
		man-nixpkgs[nixpkgs]
		man-nixos[NixOS]
	end
	subgraph source[source code]
		nix-src[NixOS/nix]
		nixpkgs-src[NixOS/nixpkgs]
	end

Contributing

Please consider contributing to this book, especially if

  • you are currently learning to use Nix
  • you have experience teaching Nix
  • you are a domain expert using Nix to solve specific problems.

Motivation

Nix has a proverbially steep learning curve.

Posted by nixinator on NixOS Discourse

The Nix[(pkgs|OS)] manuals, together with the RFCs, Eelco Dolstra’s PhD thesis The Purely Functional Software Deployment Model, NixOS Wiki and nix.dev, are the most comprehensive collection of knowledge on the design of the Nix ecosystem – except for the code base itself. But these resources are dispersed, in varying state of maintenance, do not follow a coherent structure to draw an overarching narrative, and, based on rich anecdata, community folklore, and the 2022 Nix survey, overall are not very effective for onbarding:

Documentation, Documentation, Documentation

Documentation (once again) came up universally across almost all respondents. Key asks in this area revolved around three aspects - onboarding, unblocking and centralization.

  • Onboarding - A majority of respondents highlighted trouble in the onboarding phase. The lack of new user documentation meant users have a tough time understanding how to onboard, following the first few steps, understanding best practices and finding general FAQs.
  • Unblocking - Respondents heavily emphasized the need for better documentation in the realm of tutorials/guides/examples that can help serve in unblocking themselves.
  • Centralization - Many were frustrated with the time it took to locate relevant documentation. Searching for answers took too long and invariably led them to various websites, github repos, and videos - often requiring multiple resources to address the same issue.

There also seems to exist no birds-eye view on the larger ecosystem and the interplay of its components.

Own contribution; does not cover topics such as deployment or support tooling.

Meanwhile, complexity is ever growing with new features, and disparity between what is actually explained and what people use in the field continuously increases.

Nix becomes harder to learn every day.

Project proposal

The goal of the following proposal is to make Nix the package manager as well as its sourrounding tools more accessible to Nix beginners, and enabling expert users to become effective contributors or maintainers.

Write and publish The Nix Book

The Nix Book is supposed to be the living, up-to-date overview on all concepts surrounding Nix.

The main target audience are autodidacts who do not have access to hand-holding or personal training, nor possibility for learning through osmosis. It shall contain explanations of technical principles, design rationale, and architecture of all major components in the Nix ecosystem as it is today.

It can mostly be based on available information; reoganized, reworded, or complemented where necessary. See the proposed outline and compare to current state of documentation for an impression where material can be repurposed. It should be extended with diagrams and illustrations where it would add clarity.

Hypertext allows multiple reading orders through a collection self-contained, but related units. With the right design we can offer multiple coherent access paths into conceptual knowledge; for example breadth-first, depth-first, or free link-surfing.

Ideally there should be usability tests with dedicated or in-line surveys that allow collecting feedback and checking if set learning goals have been met.

Rework the Nix manual

While the main goal is to fill the explanation gap, gaining an overview, building detailed understanding, collecting and restructuring content is already part of the task. Some of that work could therefore entail overhauling the Nix manual to better fit into the new narrative. Nix the package manager is the core component of the ecosystem and also has the smallest single manual, most amenable to structural change.

  • develop a strategy to reposition the manual as purely reference material for Nix the package manager and the Nix expression language
    • place the purpose statement prominently
      • within manual itself
      • in contribution guidelines
    • find new places for material that does not belong any more
    • @edolstra suggests to remove (or adopt in The Nix Book) the following sections
      • Introduction
      • Quick Start
      • Package Management
      • The introductory parts of "Writing Nix Expressions"
      • Glossary
  • triage, collect, or document, and keep track of all existing issues
    • conduct, lead, and coordinate attacking the issues by (however determined) priority
    • invite and enable domain experts and volunteers
      • help with merging their contributions
  • develop schemes to improve navigation and discoverability
    • links from terms to definitions
    • links to source code

Improve discoverability of existing learning material

The results of sorting through and reorganizing material for the book can be made available to the general public and already help with onboarding even before the explanations fully materialize.

  • collect and correctly categorize
  • add brief summaries to better orient readers
  • rework navigation of learning on nixos.org to incorporate the new structure
    • lead readers and contributors to the right places for their types of questions

How is success defined and measured?

In broad terms, The Nix Book and changes to documentation and web site should measurably increase probability of successful onboarding and decrease time to obtain some well-defined skill set.

Part of the tasks would be to define the learning goals, develop test questions to assess to what degree they were reached, and put up questionnaire forms in each chapter to capture the answers.

Since there are no prior metrics, setting up a preliminary questionnaire should be the first publicly visible part, presented for tutorials on the learning page, recurring community surveys, and possibly relevant sections of the manuals.

Results should help direct further work, and help answer questions such as:

  • Which questions do newcomers ask most, and do they find satisfactory answers consistent with best practice?
  • Which material should we add?
  • How should we reorganize existing material?
  • How should we improve existing material?

As a consequence we should observe influx of new regular users and contributors to nixpkgs, NixOS, and eventually Nix proper. We currently cannot measure this. Unfortunately we do not gather community metrics, and this is out of this project's scope.

License and Support

License: CC BY-SA 4.0 This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

This project is sponsored by Tweag.

More Repositories

1

nixpkgs

Nix Packages collection & NixOS
Nix
13,126
star
2

nix

Nix, the purely functional package manager
C++
9,002
star
3

patchelf

A small utility to modify the dynamic linker and RPATH of ELF executables
C
2,931
star
4

nixos-hardware

A collection of NixOS modules covering hardware quirks.
Nix
1,864
star
5

nixops

NixOps is a tool for deploying to NixOS machines in a network or cloud.
Python
1,464
star
6

nix.dev

Official documentation for getting things done with Nix.
Python
1,458
star
7

hydra

Hydra, the Nix-based continuous build system
Perl
1,128
star
8

nixfmt

The official (but not yet stable) formatter for Nix code
Nix
882
star
9

templates

Flake templates
Nix
464
star
10

nixos-search

Search NixOS packages and options
Elm
410
star
11

rfcs

The Nix community RFCs
396
star
12

cabal2nix

Generate Nix build instructions from a Cabal file
Haskell
336
star
13

nixos-homepage

Sources for nixos.org
Astro
299
star
14

nix-mode

An Emacs major mode for editing Nix expressions.
Emacs Lisp
294
star
15

nix-pills

Nix
278
star
16

ofborg

@ofborg tooling automation https://monitoring.ofborg.org/dashboard/db/ofborg
Rust
237
star
17

nixos-weekly

NixOS Weekly Newsletter
HTML
210
star
18

nixos-artwork

Nix related artwork
Nix
194
star
19

nix-idea

Nix plugin for the IntelliJ IDEA IDE
Java
176
star
20

nixos-org-configurations

NixOS configurations for nixos.org and its servers
Nix
173
star
21

nixos

OBSOLETE (go to NixOS/nixpkgs) - NixOS, a Linux distribution based on the Nix package manager - OBSOLETE (go to NixOS/nixpkgs)
Shell
169
star
22

nixpkgs-channels

DEPRECATED! Use NixOS/nixpkgs repository instead.
Nix
168
star
23

docker

DEPRECATED! Dockerfiles to package Nix in a minimal docker container
Dockerfile
148
star
24

bundlers

Nix
98
star
25

flake-registry

Global registry of Nix flakes
Shell
76
star
26

aarch64-build-box

Config for the Community aarch64 NixOS box [maintainer=@grahamc]
Nix
62
star
27

npm2nix

Generate nix expressions to build npm packages
CoffeeScript
57
star
28

nixops-aws

Python
52
star
29

nixops-hetzner

Python
49
star
30

amis

Home for NixOS AMI automation
Python
45
star
31

nixpkgs-merge-bot

Allows package maintainers to merge in nixpkgs
Python
44
star
32

nixos-wiki-infra

This project contains the setup of https://wiki.nixos.org
Nix
43
star
33

equinix-metal-builders

iPXE image for Nix builders on Equinix Metal's Spot market.
Nix
39
star
34

nixpart

NixOS storage manager/partitioner
Python
38
star
35

foundation

This is the home of the NixOS Foundation
33
star
36

nixos-channel-scripts

Perl
32
star
37

mvn2nix-maven-plugin

Generate project-info.json for use with nix's Maven repository generation functions
Java
31
star
38

security

Rust
30
star
39

language-nix

Data types and useful functions to represent and manipulate the Nix language. | Source has moved to https://github.com/nixos/cabal2nix
Haskell
30
star
40

hydra-provisioner

On-demand provisioning tool for Hydra
Python
29
star
41

nixpkgs-vet

Tool to vet (check) Nixpkgs, including its pkgs/by-name directory
Rust
23
star
42

release-wiki

19
star
43

distribution-nixpkgs

Haskell types and functions to represent, query, and manipulate the Nixpkgs distribution. | Source has moved to https://github.com/nixos/cabal2nix
Haskell
17
star
44

darwin-stubs

Text API (TAPI) files to support a pure build environment on macOS in nixpkgs.
Shell
15
star
45

mobile-nixos-website

Nix
14
star
46

reproducible.nixos.org

HTML
14
star
47

snapd-nix-base

The Nix base snap for distributing Nix-built software via the Snap store.
Nix
13
star
48

calamares-nixos-extensions

NixOS calamares [maintainer=@vlinkz]
Python
13
star
49

hackage-db

provide access to the Hackage database via Data.Map | Source has moved to https://github.com/nixos/cabal2nix
Haskell
13
star
50

rfc-steering-committee

Workflows and notes from Nix steering committee
Python
12
star
51

nixos-metrics

Rust
12
star
52

nix-eclipse

Nix Eclipse plugin
Java
12
star
53

nixos-common-styles

Common styles for NixOS related web sites.
Less
11
star
54

moderation

The home of the moderation team
11
star
55

jailbreak-cabal

Strip version restrictions from build dependencies in Cabal files.
Haskell
10
star
56

nixops-dashboard

NixOps Dashboard
9
star
57

nixos-summer

HTML
8
star
58

nixos-status

The website showing an overview status of NixOS infra and CI.
JavaScript
8
star
59

nixos-planet

XSLT
7
star
60

ofborg-viewer

Nix
6
star
61

org

Organisational documentation
Shell
6
star
62

20th-nix

20 years of Nix
HTML
5
star
63

whats-new-in-nix

Shell
5
star
64

.github

org-level github configuration
4
star
65

hydra-ant-logger

Java
4
star
66

package-list

Deprecated, use upload-nixos-package-list-to-hackage.sh instead. Generate the list of available Haskell packages for Hackage.
Haskell
3
star
67

rfc39

Implementation of NixOS RFC #39.
Nix
3
star
68

flake-regressions

Nix flake evaluation regression testing
Nix
3
star
69

rfc39-record

2
star
70

teams-collaboration

1
star
71

nix-constitutional-assembly

1
star