It is supposed to fit between first impressions on the [Nix web site](https://nixos.org) and the reference manuals for [Nix][nix manual] ([source][nix manual src]), [Nixpkgs][nixpkgs manual] ([source][nixpkgs manual src]), and [NixOS][nixos manual] ([source][nixos manual src]).
See the [vision](#vision) and [textual outline](#outline) for an idea of a desired end state.
We strongly encourage everyone interested to contribute by asking informed questions or directly proposing changes.
Make a [pull request] if you want to introduce an incremental change.
Note our [considerations on licensing and attribution](#licensing-and-attribution).
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.
Try to use it as your primary resource, however incomplete it may appear.
We ask you to liberally open issues and document all problems and questions that arise.
Please also state your learning goals and the paths you have taken so far.
Sharing your first-hand experience is invaluable to better guide our efforts, and will immediately help improve these guides for yourself and everyone else.
### You are a beginner and want to get involved in improving documentation
The documentation team is currently carrying out a documentation survey. As we work through this project, updates are made to this [Documentation Survey](./maintainers/working_groups/learning_journey/documentation-survey.md) markdown page.
Its purpose is to provide overview of the types, topics, and volume of existing documentation resources and inform future work.
We would love for you to get involved.
Here is how you can help:
1. Familiarize yourself with the format described at the top of the Documentation Survey page.
2. Contribute by making pull requests. Your change should add details to one individual link (bullet point) following the specified format.
3. Ensure consistency with existing entries. Your contributions should align with the style and format of previously added bullet points.
4. When dealing with a larger resource like the [Nixpkgs manual](https://nixos.org/manual/nixpkgs), start by creating a pull request with a structured outline. Then fill in the details section-by-section, submitting separate pull requests for each section.
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.
Does existing material on your subject meet your standards?
How could we improve it?
Is there a popular application of Nix' capabilities not yet covered?
See [Vision](#vision) for a graphical outline that illustrates the intended learning journey.
## Install Nix
Instructions for the various installation methods.
## Build and run software
Here we show how existing build plans are used to produce working software.
- Find packaged software
- Run software from existing packages
- Set up a temporary environment
The next chapter 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.
## Imperative package management
Describes a straightforward transition from temporary environments using existing packages.
- Persist packages in the file system
- Updates, rollbacks, pinning
- Garbage collection
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.
## Nix language
Leveraging the full power of Nix requires understanding the Nix language, and eventually learning to write Nix expressions.
- Syntax and semantics
- Attribute sets
- Functions
- Debugging
- Best practices
- Tooling
- Syntax highlighting
- Linters
- Formatters
## Declarative environments
While imperative package management supports "generations", it does not have proper change management, "profiles" are not portable, and it is not immediately obvious how to compose packages into a larger unit.
This section shows how to have all of that by declaring a Nix expression in a file that can be used on any system that supports Nix.
- Declare a reproducible environment
- Pinning dependencies
- Adapt packages to your needs
## Declarative package management
Here we show how existing packages come into being, and how to modify and create packages.
- Modifying existing packages
- Creating new packages
- Language ecosystems
- Contribute to Nixpkgs
Creating packages and contributing are advanced topics that require much more detail (especially langauge specifics), and are partially covered in the Nixpkgs manual already.
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.
This should be fairly superficial, otherwise it would duplicate much of the Nixpkgs manual.
Alternatively these sections could be dropped entirely, or moved to their own chapter and reference or reuse much of the Nixpkgs manual.
This is subject to refinement.
## Declarative configuration management
This section shows how the disconnected packages from previous examples can be wired up into a consistent and persistent user environment or operating system configuration.