nix.dev

nix.dev copied to clipboard

survey results, my ongoing usability study, and anecdotal evidence show that effective onboarding requires a good Nix language tutorial.

• proposal for a learning roadmap: learn language before more complex tasks
• there exist numerous tutorials
  • assess quality/effectiveness
• collect requirements for a good tutorial

closed by https://github.com/NixOS/nix.dev/pull/267

@garbas says this is top priority from marketing perspective

• @fricklerhandwerk do you have a PR for your ongoing work on a Nix language tutorial @domenkozar?
  • @domenkozar no, just a bunch of notes
    • @fricklerhandwerk I could pick that up as the next action item
      • @domenkozar would be a good first thing to contribute to nix.dev
      • would test it with newbies
        • @infinisil do you have an ongoing stream of newcomers?
          • @fricklerhandwerk usually introduce friends as absolute Nix beginners
            • sometimes coworkers from Tweag (but most have some prior experience)
            • so far only one Summer of Nix applicant showed up, sent out offering to all of them
              • would be great to establish an official pipeline for user studies to get volunteers

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

https://discourse.nixos.org/t/2022-07-07-documentation-team-meeting-notes-4/20198/1

Here is an overview of prominent/relevant tutorials/overviews of the Nix language, including the Nix manual itself, and which language features (and peculiarities) they describe or mention.

Feature \ Resource	Nix Manual	NixOS Wiki: Overview of the Nix Language	Scrive Nix Workshop	Nix by example	A Tour of Nix	Nix - A One Pager	Nix Pills	NixOS Manual: Syntax Summary
Identifiers							https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320561168
Value types overview		https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Types				https://github.com/tazjin/nix-1p#primitives--literals
String	https://nixos.org/manual/nix/unstable/language/values.html#type-string	yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#strings	https://nixos.wiki/wiki/Nix_by_example	https://nixcloud.io/tour/?id=4	https://github.com/tazjin/nix-1p#primitives--literals	https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320557968	yes
Multi-line string	https://nixos.org/manual/nix/unstable/language/values.html#type-string	yes				https://github.com/tazjin/nix-1p#primitives--literals
String interpolation Antiquotation	https://nixos.org/manual/nix/unstable/language/values.html#type-string	yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#string-interpolation		https://nixcloud.io/tour/?id=5	https://github.com/tazjin/nix-1p#primitives--literals	https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320557968	yes
Escaping rules	https://nixos.org/manual/nix/unstable/language/values.html#type-string			https://nixos.wiki/wiki/Nix_by_example#Special_characters			https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320557968
URI	https://nixos.org/manual/nix/unstable/language/values.html#type-string	yes
Integer	https://nixos.org/manual/nix/unstable/language/values.html#type-number	yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#numbers	https://nixos.wiki/wiki/Nix_by_example#Primitive_types_and_operators		https://github.com/tazjin/nix-1p#primitives--literals		yes
Floating point number	https://nixos.org/manual/nix/unstable/language/values.html#type-number	yes				https://github.com/tazjin/nix-1p#primitives--literals
Absolute path	https://nixos.org/manual/nix/unstable/language/values.html#type-path			https://nixos.wiki/wiki/Nix_by_example#Imports_and_paths
Relative path	https://nixos.org/manual/nix/unstable/language/values.html#type-path	yes	https://scrive.github.io/nix-workshop/03-nix-basics/03-files.html#path	https://nixos.wiki/wiki/Nix_by_example#Imports_and_paths		https://github.com/tazjin/nix-1p#primitives--literals		yes
Home path	https://nixos.org/manual/nix/unstable/language/values.html#type-path
<...> Search path Angle bracket syntax	https://nixos.org/manual/nix/unstable/command-ref/env-common.html?highlight=NIX_PATH#env-NIX_PATH	yes				https://github.com/tazjin/nix-1p#import--nix_path--entry
Boolean	https://nixos.org/manual/nix/unstable/language/values.html#type-boolean	yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#booleans	https://nixos.wiki/wiki/Nix_by_example#Primitive_types_and_operators				yes
Null	https://nixos.org/manual/nix/unstable/language/values.html#type-null	yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#null
List	https://nixos.org/manual/nix/unstable/language/values.html#list	yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#list	https://nixos.wiki/wiki/Nix_by_example#Lists	https://nixcloud.io/tour/?id=20	https://github.com/tazjin/nix-1p#primitives--literals	https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320525456	yes
Attribute Set	https://nixos.org/manual/nix/unstable/language/values.html#attribute-set	yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#set--object	https://nixos.wiki/wiki/Nix_by_example#Composite_data-types_and_laziness	https://nixcloud.io/tour/?id=15 https://nixcloud.io/tour/?id=16 https://nixcloud.io/tour/?id=17	https://github.com/tazjin/nix-1p#primitives--literals	https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320522768	yes
rec	https://nixos.org/manual/nix/unstable/language/constructs.html#recursive-sets	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#rec_statement		https://nixos.wiki/wiki/Nix_by_example#Lazy_loopiness_and_recursive_sets	https://nixcloud.io/tour/?id=14	https://github.com/tazjin/nix-1p#primitives--literals	https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320522768	yes
Operators overview	https://nixos.org/manual/nix/unstable/language/operators.html	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Operators		https://nixos.wiki/wiki/Nix_by_example#Primitive_types_and_operators		https://github.com/tazjin/nix-1p#operators		https://nixos.org/manual/nixos/unstable/index.html#sec-nix-syntax-summary
Function call Function application	yes		https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#function	https://nixos.wiki/wiki/Nix_by_example#Function_application	https://nixcloud.io/tour/?id=6			yes
. Attribute access Attribute selection	yes	yes https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Types	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#set--object	https://nixos.wiki/wiki/Nix_by_example#Composite_data-types_and_laziness	https://nixcloud.io/tour/?id=18 https://nixcloud.io/tour/?id=21	yes	https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320522768	yes
Nested assignment .					https://nixcloud.io/tour/?id=19 https://nixcloud.io/tour/?id=21			yes
or	yes	yes				https://github.com/tazjin/nix-1p#or-expressions		yes
// Update Merge	yes	yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#merge-objects		https://nixcloud.io/tour/?id=18	yes		yes
? Has attribute Test	yes	yes			https://nixcloud.io/tour/?id=18	yes
String concatenation +		yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#string-concatenation	yes	https://nixcloud.io/tour/?id=21	yes		yes
Integer addition +	yes	yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#numbers	yes https://nixos.wiki/wiki/Nix_by_example#Typing_discipline	https://nixcloud.io/tour/?id=21	yes		yes
Path concatenation +			https://scrive.github.io/nix-workshop/03-nix-basics/03-files.html#path-concatenation
List concatenation ++	yes	yes	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#list-concatenation		https://nixcloud.io/tour/?id=21	yes
== Equality	yes				https://nixcloud.io/tour/?id=19			yes
!= Inequality	yes				https://nixcloud.io/tour/?id=19			yes
! Negation Boolean negation	yes			https://nixos.wiki/wiki/Nix_by_example#Boolean_operators_and_laziness	https://nixcloud.io/tour/?id=19			yes
List operations				https://nixos.wiki/wiki/Nix_by_example#Lists	https://nixcloud.io/tour/?id=20
if ... else ... then Conditional Conditional expression if expression	https://nixos.org/manual/nix/unstable/language/constructs.html#conditionals		https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#if-expression	https://nixos.wiki/wiki/Nix_by_example#Conditionals		https://github.com/tazjin/nix-1p#if--then--else-	https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320515712	yes
let ... in let expression let binding	https://nixos.org/manual/nix/unstable/language/constructs.html#let-expressions	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#let_..._in_statement	https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#let-expression	https://nixos.wiki/wiki/Nix_by_example#Let_expressions https://nixos.wiki/wiki/Nix_by_example#Modules.2C_public_and_private	https://nixcloud.io/tour/?id=3 https://nixcloud.io/tour/?id=23	https://github.com/tazjin/nix-1p#variable-bindings	https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320512656	yes
with with expression with keyword	https://nixos.org/manual/nix/unstable/language/constructs.html#with-expressions	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#with_statement	https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#with-expression	https://nixos.wiki/wiki/Nix_by_example#Dynamic_scope	https://nixcloud.io/tour/?id=22	https://github.com/tazjin/nix-1p#with-statements	https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320502256	yes
inherit inheriting	https://nixos.org/manual/nix/unstable/language/constructs.html#inheriting-attributes	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#inherit_statement	https://scrive.github.io/nix-workshop/03-nix-basics/01-primitives.html#inherit		https://nixcloud.io/tour/?id=22	https://github.com/tazjin/nix-1p#inherit-keyword
assert	https://nixos.org/manual/nix/unstable/language/constructs.html#assertions			https://nixos.wiki/wiki/Nix_by_example#Assertions	https://nixcloud.io/tour/?id=25			yes
throw	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-throw		https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#lazy-evaluation	https://nixos.wiki/wiki/Nix_by_example#Exceptions
trace	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-trace			https://nixos.wiki/wiki/Nix_by_example#Debugging
Comment	https://nixos.org/manual/nix/unstable/language/constructs.html#comments
builtins overview	https://nixos.org/manual/nix/unstable/language/builtins.html					https://github.com/tazjin/nix-1p#builtins
nixpkgs/lib overview			https://scrive.github.io/nix-workshop/03-nix-basics/04-import.html#importing-global-modules			https://github.com/tazjin/nix-1p#pkgslib
pkgs overview						https://github.com/tazjin/nix-1p#pkgs-itself
mentions pkgs.stdenv.mkDerivation			https://scrive.github.io/nix-workshop/04-derivations/01-derivation-basics.html#standard-derivation			https://github.com/tazjin/nix-1p#derivations
derivation	https://nixos.org/manual/nix/unstable/language/derivations.html		https://scrive.github.io/nix-workshop/04-derivations/04-raw-derivation.html#raw-derivation			https://github.com/tazjin/nix-1p#derivations	https://nixos.org/guides/nix-pills/our-first-derivation.html#idm140737320417648
import	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-import	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Imports	https://scrive.github.io/nix-workshop/03-nix-basics/04-import.html#importing-nix-modules	https://nixos.wiki/wiki/Nix_by_example#Imports_and_paths	https://nixcloud.io/tour/?id=22	https://github.com/tazjin/nix-1p#import--nix_path--entry	https://nixos.org/guides/nix-pills/functions-and-imports.html#idm140737320444576	yes
seq	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-seq		https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#sequencing
toFile	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-toFile		https://scrive.github.io/nix-workshop/03-nix-basics/03-files.html#string-to-file
readFile	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-readFile		https://scrive.github.io/nix-workshop/03-nix-basics/03-files.html#read-file
path	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-path		https://scrive.github.io/nix-workshop/03-nix-basics/03-files.html#path-1
fetchurl	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-fetchurl		https://scrive.github.io/nix-workshop/03-nix-basics/03-files.html#fetch-url
fetchTarball	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-fetchTarball		https://scrive.github.io/nix-workshop/03-nix-basics/03-files.html#fetch-tarball
listToAttrs	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-listToAttrs				https://nixcloud.io/tour/?id=16
map	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-map				https://nixcloud.io/tour/?id=27			yes
foldl'	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-foldl'				https://nixcloud.io/tour/?id=28
hasAttr	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-hasAttr			https://nixos.wiki/wiki/Nix_by_example#Default_arguments
intersectAttrs	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-intersectAttrs				https://nixcloud.io/tour/?id=15
fromJSON	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-fromJSON				https://nixcloud.io/tour/?id=16
tryEval	https://nixos.org/manual/nix/unstable/language/builtins.html#builtins-tryEval			https://nixos.wiki/wiki/Nix_by_example#Exceptions
Anonymous functions lambda		https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Functions	https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#function	https://nixos.wiki/wiki/Nix_by_example#Function_definition		https://github.com/tazjin/nix-1p#functions	https://nixos.org/guides/nix-pills/functions-and-imports.html#idm140737320485600	yes
Single argument	https://nixos.org/manual/nix/unstable/language/constructs.html#functions	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Functions	https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#function		https://nixcloud.io/tour/?id=6		https://nixos.org/guides/nix-pills/functions-and-imports.html#idm140737320485600	yes
Currying Multiple arguments (currying) Partial application		https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Functions	https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#curried-function	https://nixos.wiki/wiki/Nix_by_example#Multi-parameter_functions_using_sets	https://nixcloud.io/tour/?id=12 https://nixcloud.io/tour/?id=13	https://github.com/tazjin/nix-1p#multiple-arguments-currying	https://nixos.org/guides/nix-pills/functions-and-imports.html#idm140737320475200
Attribute argument Destructuring Named arguments Keyword arguments Multiple arguments (attribute sets) Arguments set	https://nixos.org/manual/nix/unstable/language/constructs.html#functions	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Destructuring	https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#named-arguments	https://nixos.wiki/wiki/Nix_by_example#Multi-parameter_functions_using_sets	https://nixcloud.io/tour/?id=7	https://github.com/tazjin/nix-1p#multiple-arguments-attribute-sets	https://nixos.org/guides/nix-pills/functions-and-imports.html#idm140737320465200	yes
Default attributes Default arguments Default values	https://nixos.org/manual/nix/unstable/language/constructs.html#functions	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Default_argument	https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#default-arguments	https://nixos.wiki/wiki/Nix_by_example#Default_arguments	https://nixcloud.io/tour/?id=9	https://github.com/tazjin/nix-1p#multiple-arguments-attribute-sets	https://nixos.org/guides/nix-pills/functions-and-imports.html#idm140737320457184	yes
Ellipsis Additional attributes Optional attributes Variadic arguments Variadic attributes	https://nixos.org/manual/nix/unstable/language/constructs.html#functions	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Accepting_unexpected_attributes_in_argument_set		https://nixos.wiki/wiki/Nix_by_example#Multi-parameter_functions_using_sets		https://github.com/tazjin/nix-1p#multiple-arguments-attribute-sets	https://nixos.org/guides/nix-pills/functions-and-imports.html#idm140737320457184	yes
@-pattern @ syntax	https://nixos.org/manual/nix/unstable/language/constructs.html#functions	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Accepting_unexpected_attributes_in_argument_set			https://nixcloud.io/tour/?id=10 https://nixcloud.io/tour/?id=11	https://github.com/tazjin/nix-1p#multiple-arguments-attribute-sets		yes
Lazy	https://nixos.org/manual/nix/unstable/language/index.html	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Lazy	https://scrive.github.io/nix-workshop/03-nix-basics/02-expressions.html#lazy-evaluation	https://nixos.wiki/wiki/Nix_by_example#Boolean_operators_and_laziness https://nixos.wiki/wiki/Nix_by_example#Infinite_data_structures		https://github.com/tazjin/nix-1p#overview
Pure	https://nixos.org/manual/nix/unstable/language/index.html	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Pure		https://nixos.wiki/wiki/Nix_by_example#Recursion https://nixos.wiki/wiki/Nix_by_example#Loops.3F		https://github.com/tazjin/nix-1p#overview	https://nixos.org/guides/nix-pills/basics-of-language.html#basics-of-language
Functional	https://nixos.org/manual/nix/unstable/language/index.html	https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Functional	https://scrive.github.io/nix-workshop/01-getting-started/01-introduction.html#programming-language			https://github.com/tazjin/nix-1p#overview
Domain-specific Purpose-built	https://nixos.org/manual/nix/unstable/language/index.html					https://github.com/tazjin/nix-1p#overview
Dynamically typed			https://scrive.github.io/nix-workshop/01-getting-started/01-introduction.html#programming-language	https://nixos.wiki/wiki/Nix_by_example#Typing_discipline	https://nixcloud.io/tour/?id=24
Expressions overview		https://nixos.wiki/wiki/Overview_of_the_Nix_Language#Expressions				https://github.com/tazjin/nix-1p#overview	https://nixos.org/guides/nix-pills/basics-of-language.html#basics-of-language
Notes on errors or debugging				https://nixos.wiki/wiki/Nix_by_example#Errors	https://nixcloud.io/tour/?id=26
Notes on running examples			https://scrive.github.io/nix-workshop/02-nix-commands/03-nix--repl.html	https://nixos.wiki/wiki/Nix_by_example#REPL https://nixos.wiki/wiki/Nix_by_example#Detour:_evaluating_files			https://nixos.org/guides/nix-pills/basics-of-language.html#idm140737320582656
Additional notes	- function argument patterns do not have separate sections - function application is never shown explicitly (only in large example) - fairly good explanation of language features - is incomplete (not counting references to nixpkgs)!	- expressions are sometimes incorrectly called statements	- everything is a runnable example - no comments, examples are probably to be used as lecture slides - (attribute) sets are called objects - update is called merge - uses repl state indiscriminately - result of import is called module	- some runnable examples	- examples and exercises - imports <nixpkgs> out of thin air for Lists exercise	- assignments are called variable bindings - with is called a statement - nixpkgs manual is called Nix manual - mentions some idioms from nixpkgs and calls them Nix idioms		- assignment is called variable definition - language constructs are called control structures

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

https://discourse.nixos.org/t/2023-05-15-documentation-team-meeting-notes-48/28221/1