├── CONTRIBUTING.md ├── LICENSE.md ├── README.md ├── contents └── README.md └── resources.md /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to Nix documentation 2 | 3 | The Nix Book is a community effort to collect, create, and maintain world-class learning resources for Nix. 4 | 5 | We strongly encourage everyone interested to contribute by asking informed questions or directly proposing changes. 6 | 7 | Open an issue if you want to clarify something not evident from what is provided in this repository, or if you want to discuss a significant change before starting to work on it. 8 | 9 | Make a pull request if you want to introduce an incremental change. 10 | Note our [considerations on licensing and attribution](#licensing-and-attribution). 11 | 12 | ## You want to learn and use Nix? 13 | 14 | This book would not be possible without you. 15 | Try to use it as your primary resource, however incomplete it may appear. 16 | 17 | We ask you to liberally open issues and document all problems and questions that arise. 18 | Please also state your learning goals and the paths you have taken so far. 19 | 20 | Sharing your first-hand experience is invaluable to better guide our efforts, and will immediately help improve the book for yourself and everyone else. 21 | 22 | ## You have experience teaching Nix? 23 | 24 | You will probably have observed where learners get stuck most often, and which typical needs and questions they have. 25 | You may have your own written notes for classes, trainings, or presentations. 26 | 27 | Please share your experience and help us inform the structure and detailed contents of this book. 28 | It would be great if you could contribute examples, wordings, or illustrations that proved helpful to your students. 29 | 30 | ## You are a domain expert using Nix? 31 | 32 | If you are proficient in applying Nix to a domain-specific problem, and want to share your expertise on best practices, please check the table of contents. 33 | Does existing material on your subject meet your standards? 34 | How could we improve it? 35 | Is there a popular application of Nix' capabilities not yet covered? 36 | We would be glad to incorporate your insights. 37 | 38 | # Documentation team 39 | 40 | ## Motivation 41 | 42 | To improve the state of affairs with Nix onboarding and documentation, we have to tackle some big issues and work through many small ones: 43 | implement structural changes after gathering the necessary social support; 44 | fix numerous little problems and help people get their contributions merged. 45 | 46 | It requires significant time or resources to do this effectively and consistently. 47 | The team is built around that limitation, and therefore organized as a praxicracy: 48 | you are in charge if and only if you get the work done. 49 | 50 | The team’s reason to exist is to make that principle discoverable and reproducible by laying groundwork and setting examples. 51 | 52 | ## Goals 53 | 54 | - ease Nix learning, increase onboarding success and user retention 55 | - improve organization of Nix knowledge 56 | - lead, guide, and support community efforts 57 | 58 | ## Members 59 | 60 | - Valentin Gagarin (@fricklerhandwerk) (lead until 2022-10-31) 61 | 62 | Nix documentarian, [Tweag](tweag.io) 63 | 64 | - Jörg Thalheim (@Mic92) 65 | 66 | NixOS Wiki maintainer 67 | 68 | - Domen Kožar (@domenkozar) 69 | 70 | [nix.dev](http://nix.dev) author, [Cachix](cachix.org) 71 | 72 | ## Meeting protocol 73 | 74 | The team holds bi-weekly meetings on Thursdays 17:30 (Europe/Berlin). 75 | Meetings are announced on the [Discourse community calendar](https://discourse.nixos.org/t/community-calendar/18589). 76 | 77 | Meeting agendas are set on [the team's GitHub project board](https://github.com/orgs/NixOS/projects/15) from issues and pull requests. 78 | Pull requests have priority, and authors are invited to the meetings. 79 | Estimated discussion time is annotated for each agenda item and is expected to be followed. 80 | 81 | Each meeting begins with determining a scribe to take notes, and a moderator to keep focus and schedule. 82 | Notes are prepared in a [HackMD](https://hackmd.io/) scratchpad, and added to the respective issue or pull request as a comment. 83 | 84 | All notes are posted on the [Discourse documentation team category](https://discourse.nixos.org/c/governance/documentation-team/43). 85 | 86 | Notes should contain: 87 | - date of meeting 88 | - list of attendees 89 | - links to GitHub comments from agenda items 90 | 91 | # Guidelines 92 | 93 | Here are values and practical guidelines to go by when contributing. 94 | 95 | ## Values 96 | 97 | ### Be kind 98 | 99 | Adapted from [Contributor Covenant](contributor-covenant) and [The Carpentries Code of Conduct](carpentries-coc): 100 | 101 | - Use welcoming and inclusive language 102 | - Show empathy and respect towards other people 103 | - Be respectful of different viewpoints and experiences 104 | - Give and gracefully accept constructive criticism 105 | - Focus on what is best for the community 106 | 107 | [contributor-covenant]: https://github.com/EthicalSource/contributor_covenant/blob/cd7fcf684249786b7f7d47ba49c23a6bcb3233eb/content/version/2/1/code_of_conduct.md?plain=1#L25-L31 108 | [carpentries-coc]: https://github.com/carpentries/docs.carpentries.org/blob/4691971d9f49544054410334140a4fd391a738da/topic_folders/policies/code-of-conduct.md?plain=1#L15-L19 109 | 110 | ### Be truthful 111 | 112 | The only thing more confusing than no documentation is misleading documentation. 113 | 114 | #### Use and provide evidence 115 | 116 | This book should enable readers to answer all their questions on their own. 117 | 118 | Provide [links](#links) to the [online Nix manual][nix-manual] or other resources, if it would help guide readers on their learning journey. 119 | It is explicitly within scope of this project, and encouraged by Nix maintainers, to update or restructure the [Nix manual source code][nix-manual-src] where appropriate, to improve the overall experience. 120 | 121 | Similarly, the other information in this repository should enable contributors to answer most of their questions and correct obvious errors on their own, and only then resort to opening issues. 122 | 123 | Errors get more obvious if we can measure execution against intent. 124 | Therefore we ask you to always make explicit the motivation behind your proposed changes. 125 | 126 | Add references to any relevant resources in commit messages, if it helps understand the reasoning behind a significant change. 127 | 128 | [nix-manual]: https://nixos.org/manual/nix/stable/ 129 | [nix-manual-src]: https://github.com/NixOS/nix/tree/master/doc/manual 130 | 131 | #### Ensure working code samples 132 | 133 | Code samples must always be working correctly when run as instructed. 134 | Nix provides us with everything needed to make this happen. 135 | 136 | Currently we have no automated tooling in place to assist with this, and pull requests to address that question are very welcome. 137 | 138 | ### Be concise 139 | 140 | > I would have written a shorter letter, but I did not have the time. 141 | > 142 | > — [Blaise Pascal][shorter-letter] 143 | 144 | This book is for the readers, and their time and attention is limited. 145 | Take the time to be extraordinarily respectful with their cognitive resources. 146 | 147 | You can use diagrams or illustrations to support written descriptions. 148 | [GitHub allows creating Mermaid diagrams within Markdown.][github-mermaid] 149 | 150 | The same holds for communication directed to contributors and maintainers: 151 | This is a public project, and many people will read what you write. 152 | Use this leverage with care. 153 | 154 | [shorter-letter]: https://en.m.wikiquote.org/w/index.php?title=Blaise_Pascal&oldid=2978584#Quotes 155 | [github-mermaid]: https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/ 156 | 157 | ## Guides 158 | 159 | ### How to contribute effectively? 160 | 161 | Different audiences require different levels of sophistication, and both readers' and contributors' available time and expertise varies widely. 162 | 163 | The following diagram shows a pipeline for contributions to learning material and documentation. 164 | Use it to decide where to best put the results of your efforts, depending on how much time you can spend on refining them to get accepted. 165 | 166 | Communication platforms are distinguished by mode of interaction: 167 | - append to streams 168 | - amount of infomation grows without bounds 169 | - only recent items are relevant 170 | - change artifacts 171 | - amount of information is strictly bounded 172 | - all items are relevant 173 | 174 | Arrows point towards 175 | - decreasing rate of change 176 | - increasing public visibility 177 | - increasing amount of scrutiny. 178 | 179 | Arrows indicate possibilities to promote existing material to more prominent and more easily discoverable locations. 180 | 181 | ```mermaid 182 | flowchart 183 | Matrix --> |filter| Discourse 184 | events[meetings and events] --> |report| Discourse 185 | external[external sources] --> |collect| Discourse 186 | Discourse --> |design| RFCs 187 | Discourse --> |change| code 188 | Discourse --> |learn| Wiki 189 | Wiki --> |refine| manuals --> |guide| book[The Nix Book] --> |show| www[web site] 190 | RFCs --> code --> |document| manuals 191 | subgraph stream 192 | Matrix 193 | events 194 | external 195 | Discourse 196 | RFCs 197 | end 198 | subgraph artifact 199 | Wiki 200 | code 201 | manuals 202 | book 203 | www 204 | end 205 | ``` 206 | 207 | - Matrix 208 | 209 | Use Matrix for casual communication. 210 | 211 | The documentation team frequents the [Nix\* Documentation][matrix] room. 212 | 213 | Old messages are extremely improbable to be read by anyone. 214 | Feel free to post what you have found valuable on [Discourse][discourse]. 215 | 216 | - meetings and events 217 | 218 | Check the [Discourse community calendar][calendar] for real-time events. 219 | 220 | The documentation team holds regular meetings and posts meeting notes in the [Documentation][docs] category. 221 | 222 | - external sources 223 | 224 | The Internet is full of helpful resources concerning Nix. 225 | Feel free to share what you have found valuable on Discourse in the [Links][links] category. 226 | 227 | - Discourse 228 | 229 | [Discourse][discourse] is the central community hub. 230 | This is the place for your questions, suggestions, and discussion. 231 | 232 | The documentation team monitors the [Documentation][docs] category. 233 | 234 | Old threads and especially posts in long threads are improbable to be read by many people. 235 | Feel free to write down what you have learned in a [NixOS Wiki][wiki] article, or update an existing article. 236 | 237 | - Wiki 238 | 239 | [NixOS Wiki][wiki] is a collection of interlinked guides to solve well-known problems. 240 | It is collectively edited by the community. 241 | 242 | The Wiki is a dumping ground for Nix knowledge. 243 | Its purpose is to quickly and conveniently collect insights and make them readily available when needed. 244 | It covers a broad range of topics, is only loosely organized, and does not impose quality standards. 245 | 246 | The documentation team monitors changes to maintain an overview of topics of interest and prevent vandalism. 247 | 248 | You can help with 249 | - improving discoverability by adding categorization. 250 | - clarifying articles and correcting errors 251 | - migrating information to other resources. 252 | 253 | Guidelines for migration: 254 | - Nix interaction: [Nix manual][nix-manual] 255 | - Language-specific build instructions: [Nixpkgs manual][nixpkgs-manual] 256 | - Package, service, or hardware configuration: [NixOS manual][nixos-manual] 257 | - Ecosystem overview and best practices: [The Nix Book][book] 258 | 259 | - manuals 260 | 261 | The manuals for 262 | - [Nix][nix-manual] 263 | - [Nixpkgs][nixpkgs-manual] 264 | - [NixOS][nixos-manual] 265 | 266 | are primarily reference documentation, specifying interfaces and behavior. 267 | They also show example interactions to show how to use its components, and explain mechanisms where necessary. 268 | 269 | The documentation team assists contributors to get their changes to the manuals merged. 270 | 271 | - The Nix Book 272 | 273 | The book's purpose is to guide newcomers by teaching essential Nix knowledge, show best practices, and help orient users in the Nix ecosystem. 274 | It goes into breadth, not depth. 275 | 276 | The documentation team maintains The Nix Book as editors. 277 | 278 | - web site 279 | 280 | The Nix project web site is [nixos.org][www]. 281 | Web site contents that concern learning Nix should reference or include material from The Nix Book. 282 | 283 | The [Nix markting team][marketing] is responsible for the web site, and the documentation team assists with maintaining contents related to onboarding. 284 | 285 | [matrix]: https://app.element.io/#/room/#docs:nixos.org 286 | [calendar]: https://discourse.nixos.org/t/community-calendar/18589 287 | [discourse]: https://discourse.nixos.org/ 288 | [wiki]: https://nixos.wiki/ 289 | [howto]: https://discourse.nixos.org/c/howto/15 290 | [docs]: https://discourse.nixos.org/c/dev/documentation/25 291 | [links]: https://discourse.nixos.org/c/links/12 292 | [nix]: https://github.com/NixOS/nix 293 | [nixpkgs]: https://github.com/NixOS/nixpkgs 294 | [book]: https://github.com/NixOS/nix-book 295 | [marketing]: https://nixos.org/community/teams/marketing.html 296 | [www]: https://nixos.org 297 | 298 | ### How to help immediately? 299 | 300 | You can always help out by 301 | - converting [Howto] posts can be to Wiki pages. 302 | Add a link from the thread to the page to guide readers. 303 | 304 | ### File organization 305 | 306 | ``` 307 | ├── README.md | project front page on GitHub 308 | ├── CONTRIBUTING.md | this file 309 | ├── LICENSE.md | license information 310 | ├── resources.md | categorized collection of existing learning resources 311 | └── contents | book contents 312 | ``` 313 | 314 | ### Licensing and attribution 315 | 316 | When opening pull requests with your own contributions, you agree to licensing your work under [CC-BY-SA 4.0][cc-by-sa]. 317 | You will be considered co-author of this book, as recorded by version history. 318 | 319 | When adding material by third parties, make sure it has a matching license that permits this. 320 | In that case, [unambiguously](#links) state source, authors, and license. 321 | Also [add the original author as co-author][github-multiple-authors] to the respective change, so we can track authorship through version history. 322 | 323 | Notify the authors *before* using their work. 324 | 325 | [cc-by-sa]: https://creativecommons.org/licenses/by-sa/4.0/ 326 | [github-multiple-authors]: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors 327 | 328 | ### Links 329 | 330 | Unless explicitly required to point to the latest version of an external resource, all references should be [permanent links][permalink]. 331 | 332 | Many web services offer permalinks. 333 | Examples: 334 | - [GitHub URLs to specific commits][github-permalink] 335 | - [Wikipedia URLs to specific page versions][wikipedia-permalink] 336 | - [Internet Archive "Save Page Now" for persisting web pages][internet-archive-save] 337 | 338 | [permalink]: https://en.m.wikipedia.org/wiki/Permalink 339 | [github-permalink]: https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files 340 | [wikipedia-permalink]: https://en.m.wikipedia.org/wiki/Wikipedia:Linking_to_Wikipedia#Permanent_links_to_old_versions_of_pages 341 | [internet-archive-save]: https://web.archive.org/save 342 | 343 | ### Markdown 344 | 345 | Write one sentence per line. 346 | This makes it easier to manage changes. 347 | The rule is unambiguous and does not require tooling support to be applied easily. 348 | 349 | [Here is a discussion of different line wrapping styles.][markdown-wrapping-styles] 350 | 351 | Use [reference links][reference-link] to keep the plain text readable. 352 | Collect links at the end of each section, which are delimited by headings. 353 | 354 | [markdown-wrapping-styles]: https://web.archive.org/web/20220519121408/https://mtsknn.fi/blog/4-1-wrapping-styles-for-markdown-prose-and-code-comments/ 355 | [reference-link]: https://github.github.com/gfm/#reference-link 356 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. 2 | To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. 3 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The Nix Book 2 | 3 | > **Warning** 4 | > This repository may eventually disappear. 5 | > 6 | > The [Nix documentation team][docs-team] now works on [nix.dev][nix-dev] towards the vision outlined here. 7 | 8 | [docs-team]: https://discourse.nixos.org/t/documentation-team-flattening-the-learning-curve/20003 9 | [nix-dev]: https://github.com/NixOS/nix.dev 10 | 11 | 12 | ## A vision for the journey into Nix, `nixpkgs`, and NixOS 13 | 14 | This book is supposed to fit between first impressions on the [Nix web site][nixos-org] and the reference manuals for [Nix][nix-manual], [Nixpkgs][nixpkgs-manual], [NixOS][nixos-manual]. 15 | 16 | ```mermaid 17 | flowchart 18 | subgraph homepage 19 | core --> explore 20 | get-started --> learn 21 | explore --> |details| how-nix-works 22 | subgraph front-page[front page] 23 | subgraph core[core features] 24 | same[always working environment, everywhere] 25 | polyglot[many programming languages] 26 | deploy[configure, build, deploy] 27 | rollbacks[roll back any time] 28 | community[global community] 29 | end 30 | examples 31 | get-started[get started] 32 | end 33 | subgraph explore 34 | complete[complete dependencies] 35 | reproducible[reproducible builds] 36 | correct[correct deployment] 37 | multiple[multiple versions] 38 | atomic[atomic upgrades] 39 | agnostic[many programming languages] 40 | caching[transparent caching] 41 | remote[remote builds] 42 | nixpkgs[community package collection] 43 | nixexpr[purely functional configuration language] 44 | end 45 | subgraph learn 46 | install 47 | first-steps[first steps] 48 | how-nix-works[how nix works] 49 | end 50 | end 51 | first-steps --> book --> manuals --> source 52 | book --> discussion 53 | subgraph book[The Nix Book] 54 | direction TB 55 | build --> imperative-pkgs & declarative-pkgs 56 | declarative-pkgs --> writing --> declarative-config & dev & nixpkgs-learn 57 | subgraph build[run software] 58 | direction LR 59 | find-pkg[find packages] 60 | run[run a program] 61 | shell[set up temporary environment] 62 | end 63 | subgraph imperative-pkgs[imperative package management] 64 | direction LR 65 | install-profile[install] 66 | update 67 | rollback 68 | pin-packages[pin packages] 69 | end 70 | subgraph declarative-pkgs[declarative package management] 71 | direction LR 72 | decl-env[reproducible environment] 73 | compose[compose packages] 74 | adapt[adapt packages] 75 | pin-deps[pin dependencies] 76 | gc[garbage collection] 77 | end 78 | subgraph nixpkgs-learn[package collection] 79 | direction LR 80 | modify[modify existing package] 81 | newpkg[create new package] 82 | contribute-nixpkgs[contribute to nixpkgs] 83 | end 84 | subgraph declarative-config[declarative configuration management] 85 | direction LR 86 | user-env[user environments] 87 | os[operating system distribution] 88 | services[service management] 89 | end 90 | subgraph writing[configuration language] 91 | syntax 92 | functions 93 | attrsets[attribute sets] 94 | debugging 95 | library 96 | tools[tool support] 97 | end 98 | subgraph dev[software development] 99 | direction LR 100 | lang-ecosystems[language ecosystems] 101 | caching 102 | deployment 103 | ci[continuous integration] 104 | distributed[distributed builds] 105 | cross-compilation 106 | bundling[bundling build results] 107 | end 108 | end 109 | subgraph discussion 110 | RFCs 111 | pr[pull requests] 112 | issues 113 | Discourse 114 | end 115 | subgraph manuals 116 | subgraph man-nix[Nix] 117 | cmd[command line interface] 118 | lang[expression language] 119 | config[configuration] 120 | architecture 121 | end 122 | man-nixpkgs[nixpkgs] 123 | man-nixos[NixOS] 124 | end 125 | subgraph source[source code] 126 | nix-src[NixOS/nix] 127 | nixpkgs-src[NixOS/nixpkgs] 128 | end 129 | 130 | ``` 131 | ## Contributing 132 | 133 | Please consider [contributing to this book](CONTRIBUTING.md), especially if 134 | 135 | - you are currently learning to use Nix 136 | - you have experience teaching Nix 137 | - you are a domain expert using Nix to solve specific problems. 138 | 139 | [nixos-org]: https://nixos.org 140 | [nix-manual]: https://nixos.org/manual/nix/stable/ 141 | [nixpkgs-manual]: https://nixos.org/manual/nixpkgs/stable/ 142 | [nixos-manual]: https://nixos.org/manual/nixos/stable/ 143 | 144 | # Motivation 145 | 146 | Nix has a proverbially steep learning curve. 147 | 148 | > ![](https://discourse.nixos.org/uploads/default/original/2X/f/fef4e7f73fbca41179060500174f1448d16fb8c9.jpeg) 149 | > 150 | > [Posted by nixinator](https://discourse.nixos.org/t/probably-the-best-lecture-of-nix-fundamentals-on-the-internet/9893) on NixOS Discourse 151 | 152 | The [Nix](https://nixos.org/manual/nix/stable/)[([pkgs](https://nixos.org/manual/nixpkgs/stable)|[OS](https://nixos.org/manual/nixos/stable/))] manuals, together with the [RFCs](https://github.com/NixOS/rfcs), Eelco Dolstra’s PhD thesis [The Purely Functional Software Deployment Model](https://edolstra.github.io/pubs/phd-thesis.pdf), [NixOS Wiki](https://nixos.wiki/wiki/) and [nix.dev](https://nix.dev), are the most comprehensive collection of knowledge on the design of the Nix ecosystem – except for the code base itself. 153 | 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](https://discourse.nixos.org/t/2022-nix-survey-results/18983), overall are not very effective for onbarding: 154 | 155 | > ### Documentation, Documentation, Documentation 156 | > 157 | > Documentation (once again) came up universally across almost all respondents. 158 | Key asks in this area revolved around three aspects - onboarding, unblocking and centralization. 159 | > 160 | > - Onboarding - A majority of respondents highlighted trouble in the onboarding phase. 161 | 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. 162 | > - Unblocking - Respondents heavily emphasized the need for better documentation in the realm of tutorials/guides/examples that can help serve in unblocking themselves. 163 | > - Centralization - Many were frustrated with the time it took to locate relevant documentation. 164 | 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. 165 | 166 | There also seems to exist no birds-eye view on the larger ecosystem and the interplay of its components. 167 | 168 | > ![](https://discourse.nixos.org/uploads/default/original/2X/b/b0c3368ce1a5b94b061184f98a8db49bfd209c51.png) 169 | > 170 | > Own contribution; does not cover topics such as deployment or support tooling. 171 | 172 | Meanwhile, complexity is ever growing with new features, and disparity between what is actually explained and what people use in the field continuously increases. 173 | 174 | Nix becomes harder to learn every day. 175 | 176 | # Project proposal 177 | 178 | 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. 179 | 180 | ## Write and publish **The Nix Book** 181 | 182 | The Nix Book is supposed to be the living, up-to-date overview on all concepts surrounding Nix. 183 | 184 | 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. 185 | 186 | It can mostly be based on available information; reoganized, reworded, or complemented where necessary. See the [proposed outline](contents/README.md) and compare to [current state of documentation](resources.md) for an impression where material can be repurposed. It should be extended with diagrams and illustrations where it would add clarity. 187 | 188 | 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. 189 | 190 | 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. 191 | 192 | ## Rework the Nix manual 193 | 194 | 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. 195 | 196 | - develop a strategy to reposition the manual as purely reference material for Nix the package manager and the Nix expression language 197 | - place the purpose statement prominently 198 | - within manual itself 199 | - in contribution guidelines 200 | - find new places for material that does not belong any more 201 | - @edolstra suggests to remove (or adopt in The Nix Book) the following sections 202 | - Introduction 203 | - Quick Start 204 | - Package Management 205 | - The introductory parts of "Writing Nix Expressions" 206 | - Glossary 207 | - triage, collect, or document, and keep track of all existing issues 208 | - conduct, lead, and coordinate attacking the issues by (however determined) priority 209 | - invite and enable domain experts and volunteers 210 | - help with merging their contributions 211 | - develop schemes to improve navigation and discoverability 212 | - links from terms to definitions 213 | - links to source code 214 | 215 | ## Improve discoverability of existing learning material 216 | 217 | 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. 218 | 219 | - collect and correctly categorize 220 | - similar to or based on [an initial survey of existing resources](resources.md) 221 | - through the lens of [Backward design](https://en.wikipedia.org/wiki/Backward_design) 222 | - what are learning objectives and which material achieves which? 223 | - add brief summaries to better orient readers 224 | - rework navigation of learning on [nixos.org][nixos-org] to incorporate the new structure 225 | - lead readers and contributors to the right places for their types of questions 226 | 227 | ## How is success defined and measured? 228 | 229 | 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. 230 | 231 | 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. 232 | 233 | 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](https://nixos.org/learn), [recurring community surveys](https://discourse.nixos.org/t/nix-community-survey-2022-update/18733), and possibly relevant sections of the manuals. 234 | 235 | Results should help direct further work, and help answer questions such as: 236 | 237 | - Which questions do newcomers ask most, and do they find satisfactory answers consistent with best practice? 238 | - Which material should we add? 239 | - How should we reorganize existing material? 240 | - How should we improve existing material? 241 | 242 | 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. 243 | 244 | # License and Support 245 | 246 | [![License: CC BY-SA 4.0][cc-by-sa-button]][cc-by-sa] 247 | This work is licensed under a [Creative Commons Attribution-ShareAlike 4.0][cc-by-sa] International License. 248 | 249 | This project is sponsored by [Tweag][tweag]. 250 | 251 | [cc-by-sa]: https://creativecommons.org/licenses/by-sa/4.0/ 252 | [cc-by-sa-button]: https://licensebuttons.net/l/by-sa/4.0/80x15.png 253 | [tweag]: https://www.tweag.io 254 | 255 | -------------------------------------------------------------------------------- /contents/README.md: -------------------------------------------------------------------------------- 1 | # Outline 2 | 3 | ## How to read this book 4 | 5 | Each section has the following structure: 6 | 7 | - What will you learn? (problem statement and learning goals) 8 | - What do you need? (prerequisites) 9 | - Previous chapters 10 | - Domain-specific skills or knowledge 11 | - How easy is it? (level of difficulcy) 12 | - Some things are trivial and fun. 13 | - Some things require disciplined learning to get productive. 14 | - Some things do not work properly, have confusing interfaces, or inadequate documentation. 15 | 16 | - How to do it? (instructions) 17 | 18 | Depending on how well a use case is supported, we can provide 19 | - instructions and examples 20 | - links to known-good external resources, with summaries 21 | - overview of available tools, and their state of maturity and maintenance 22 | - overview of ideas, and state of community discussion. 23 | 24 | - What did you learn? (assessment) 25 | 26 | To further improve the book, the tools and their documentation, we assess your learning success. 27 | You can also ask questions, and leave feedback or suggestions. 28 | 29 | - (optional) How does it work? (explanation) 30 | 31 | For the curious: a brief explanation of the mechanism behind the solution Nix offers. 32 | 33 | - How to continue from here? (next steps) 34 | 35 | Depending on how well a use case is explored, you can proceed to 36 | - other chapters 37 | - reference manuals 38 | - external projects 39 | - ongoing community discussion. 40 | 41 | Chapters and sections are ordered by increasing level of difficulcy. 42 | 43 | ## How Nix works 44 | 45 | Nix offers a novel paradigm to build software and manage computer systems. 46 | 47 | This section briefly explains design rationale, high-level architecture, and general mechanism behind Nix. 48 | 49 | - package manager 50 | - configuration language 51 | - build system 52 | 53 | ## What you can do with Nix 54 | 55 | ### prerequisites 56 | 57 | - required skills and knowledge 58 | - install Nix 59 | 60 | ### build and run software 61 | 62 | Here we show how existing build plans are used to produce working software. 63 | 64 | - find packaged software 65 | - run software from existing packages 66 | - set up a temporary environment 67 | 68 | ### package management 69 | 70 | This chapter is about how to hold onto the ephemeral examples from the previous chapter, and how to create more complex environments by composing existing packages. 71 | 72 | #### imperative package management 73 | 74 | Describes a straightforward transition from temporary environments using existing packages. 75 | 76 | - persist packages in the file system 77 | - updates, rollbacks, pinning 78 | - garbage collection 79 | 80 | Imperative package management's unique feature is that it allows updating each package independently to the most recent available version without touching the rest of the system. 81 | 82 | #### declarative package management 83 | 84 | While imperative package management supports "generations", it does not have proper change management, "profiles" are not portable, and it is not possible to compose packages into a larger unit. 85 | This section shows how to have all of that by declaring a Nix expression in a file. 86 | 87 | - declare a reproducible environment 88 | - compose packages 89 | - adapt packages to your needs 90 | 91 | ### configuration language 92 | 93 | - syntax 94 | - functions 95 | - attribute sets 96 | - debugging 97 | - library 98 | - tool support 99 | - syntax highlighting 100 | - linters 101 | - formatters 102 | 103 | ### maintain package collection 104 | 105 | Explain how existing packages come into being, and show how to modify and create packages. 106 | 107 | - modify existing package 108 | - create new package 109 | - contribute to public repository 110 | 111 | Creating packages and contributing are advanced topics that require much more detail (especially langauge specifics), and are partially covered in the `nixpkgs` manual already. 112 | In this context they are intended to demonstrate `nixpkgs` architecture and design, to enable readers to navigate existing code, assess pull requests, and create or maintain their own packages. 113 | This should be fairly superficial, otherwise it would duplicate much of the `nixpkgs` manual. 114 | Alternatively these sections could be dropped entirely, or moved to their own chapter and reference or reuse much of the `nixpkgs` manual. 115 | 116 | ### declarative configuration management 117 | 118 | Show how the disconnected packages from previous examples can be wired up into a consistent and persistent user environment or operating system configuration. 119 | 120 | - user environments 121 | - operating system distribution 122 | - service management 123 | 124 | ### software development 125 | 126 | - language ecosystems 127 | - caching 128 | - deployment 129 | - continuous integration 130 | - distributed builds 131 | - cross-compilation 132 | - bundling build results 133 | - virtual machines 134 | - docker containers 135 | 136 | -------------------------------------------------------------------------------- /resources.md: -------------------------------------------------------------------------------- 1 | # Current state of documentation 2 | 3 | > ![](https://documentation.divio.com/_images/overview.png) 4 | > 5 | > [The documentation system](https://documentation.divio.com/), a framework to think about various types of documentation, each with their own purpose and capabilities. 6 | 7 | When viewed in the framework of [The documentation system](https://documentation.divio.com), we observe the following. 8 | 9 | The manuals appear not to be maintained in any coordinated fashion, supposedly due to their ever increasing size. They do not serve a clear-cut purpose, and are instead somewhere in between an explanation and a reference, fulfilling both roles only partially. 10 | 11 | There exist many resources showing *how to use* Nix or NixOS or interact with `nixpkgs`, some in writing, some as instructional videos. 12 | 13 | There exists an overwhelming amount of “Nix” explanations, all of which *only* refer to the Nix configuration language. 14 | 15 | There seems to exist no self-contained, complete, up-to-date **explanation** of Nix the package manager, NixOS, or `nixpkgs` with respect to fundamental operating principles, architecture and design decisions! @edolstra’s thesis is still the most comprehensive source on rationale, yet only covers Nix language and package manager in depth. 16 | 17 | Given [the thesis has been removed from the NixOS web site in 2017](https://github.com/NixOS/nixos-homepage/issues/830), we can assume that more recent Nix newcomers do not even know it exists. As the thesis is not a living document, it is necessarily outdated in some regards. It still has the most precise conceptual explanations, and presenting them in accessible form would already improve the state of affairs. 18 | 19 | 41 |
20 | 21 | ### Tutorials 22 | 23 | Nix language 24 | - [learn Nix in Y minutes](https://learnxinyminutes.com/docs/nix/) 25 | - [Tour of Nix](https://nixcloud.io/tour/?id=1) 26 | - [Nix by example](https://medium.com/@MrJamesFisher/nix-by-example-a0063a1a4c55) 27 | - [Nix Language Overview](https://www.youtube.com/watch?v=eCapIx9heBw&list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&index=5) 28 | - [Nix Pills Chapter 4](https://nixos.org/guides/nix-pills/basics-of-language.html) and [5](https://nixos.org/guides/nix-pills/functions-and-imports.html) 29 | 30 | Nixpkgs 31 | - [Nix Shell Overview](https://www.youtube.com/watch?v=SGekN4pDExY&list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&index=6) 32 | - [Nix Fundamentals](https://www.youtube.com/watch?v=m4sv2M9jRLg) 33 | - [Nix Pills Chapter 8](https://nixos.org/guides/nix-pills/generic-builders.html), [9](https://nixos.org/guides/nix-pills/automatic-runtime-dependencies.html), [10](https://nixos.org/guides/nix-pills/developing-with-nix-shell.html), [12](https://nixos.org/guides/nix-pills/inputs-design-pattern.html), [13](https://nixos.org/guides/nix-pills/callpackage-design-pattern.html), [14](https://nixos.org/guides/nix-pills/override-design-pattern.html), [16](https://nixos.org/guides/nix-pills/nixpkgs-parameters.html), [17](https://nixos.org/guides/nix-pills/nixpkgs-overriding-packages.html), [19](https://nixos.org/guides/nix-pills/fundamentals-of-stdenv.html), [20](https://nixos.org/guides/nix-pills/basic-dependencies-and-hooks.html) 34 | 35 | NixOS 36 | - [NixOS Filesystem Overview](https://www.youtube.com/watch?v=jf0nIn2oS8A&list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&index=4) 37 | 38 | Nix package manager 39 | - [Nix Pills Chapter 3](https://nixos.org/guides/nix-pills/enter-environment.html), [6](https://nixos.org/guides/nix-pills/our-first-derivation.html), [7](https://nixos.org/guides/nix-pills/working-derivation.html), [11](https://nixos.org/guides/nix-pills/garbage-collector.html), [15](https://nixos.org/guides/nix-pills/nix-search-paths.html), [18](https://nixos.org/guides/nix-pills/nix-store-paths.html) 40 | 42 | 43 | ### How-To Guides 44 | 45 | Nix language 46 | 47 | Nixpkgs 48 | - [NixOS Wiki FAQ](https://nixos.wiki/wiki/FAQ) 49 | - [nix.dev guides](https://nix.dev/) 50 | - [Jon Ringer’s videos](https://www.youtube.com/channel/UC-cY3DcYladGdFQWIKL90SQ) 51 | - [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable) 52 | 53 | NixOS 54 | - [nix.dev guides](https://nix.dev/) 55 | - [Jon Ringer’s videos](https://www.youtube.com/channel/UC-cY3DcYladGdFQWIKL90SQ) 56 | - [Nix notes](https://github.com/noteed/nix-notes) 57 | - [NixOS Manual](https://nixos.org/manual/nixos/stable/) 58 | 59 | Nix package manager 60 | - [NixOS Wiki: Managing the Store](https://nixos.wiki/wiki/Nix_Cookbook#Managing_storage)
61 | 62 | ### Explanation 63 | 64 | Nix language 65 | 66 | - [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf) 67 | 68 | Nixpkgs 69 | - [Nix Pills, partial](https://nixos.org/guides/nix-pills/index.html) 70 | - [Connecting Bash to Nix](https://www.zombiezen.com/blog/2023/03/connecting-bash-to-nix/) 71 | 72 | NixOS 73 | 74 | Nix package manager 75 | - [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf) 76 | 77 | ### Reference 78 | 79 | Nix language 80 | - [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf) 81 | - [Nix manual (writing Nix expressions)](https://nixos.org/manual/nix/stable/expressions/writing-nix-expressions.html) 82 | - [one-page reference](https://github.com/tazjin/nix-1p) 83 | 84 | Nixpkgs 85 | - [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable) 86 | 87 | NixOS 88 | - [NixOS manual](https://nixos.org/manual/nixos/stable) 89 | 90 | Nix package manager 91 | - [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf) 92 | - [Nix manual (command reference)](https://nixos.org/manual/nix/stable/command-ref/command-ref.html) 93 |
94 | 95 | 96 | > Note that we have significantly more how-to material than anything else, which does not show prominently in the table because is summarized in NixOS Wiki and nix.dev. 97 | --------------------------------------------------------------------------------