* front page: Who is Nix for?
For at least two years there were ongoing debates about the target
audience of the Nix ecosystem. Nix maintainers did not manage to
converge on a statement [0]. The marketing team is explicitly focusing
on software developers [1], and the documentation team was supposed to
align with that from the very beginning [2].
What was missing so far was what we mean by "software developers".
Arguably, it encompasses a particular mind set about how to deal with
computers and enough time to learn things.
And while for documentation it matters most *what* the software is doing
rather than *who* it is made for (or by), the ecosystem is a community
effort, and people matter [3]. So far, we haven't really identified the
(eventual) boundaries of this community (at least I don't know of any
serious attempt), which also plays into the definition of a target
audience. Yet, in practice, not every contribution, not every question
or comment is treated equally, and this has reasons in our implicit
assumptions about who belongs.
This is an attempt to draw such a boundary that is not arbitrary, and
neither to narrow nor too wide. The goal is, as always, to help
Nix beginners set realistic expectations for their journey.
The list of occupations/interests who may benefit from Nix is based on
the 2022 [4] and 2023 [5] community surveys.
[0]: https://github.com/NixOS/nix/pull/7156
[1]: 76d42a052d/community/teams/marketing.tt (L89)
[2]: https://discourse.nixos.org/t/2022-06-15-documentation-team-meeting-notes-1/20004
[3]: https://discourse.nixos.org/t/zurich-23-05-zhf-hackathon-and-workshop-report/29093#ux-workshop-21
[4]: https://discourse.nixos.org/t/2022-nix-survey-results/18983
[5]: https://discourse.nixos.org/t/nix-community-survey-2023-results/33124
Co-authored-by: Daniel Sidhion <DanielSidhion@users.noreply.github.com>
the good stuff was historically hard to discover.
so hard that I found a new one just today...
- add Nixology
- remove the Nix Fundamentals, because it's better covered by Nixology
- add The Nix Hour
- add NixCon
- collapse Jon Ringer's videos into one link
- link to all of Wil Taylor's videos
- re-order the "other" articles to roughly match nix.dev contents
As it was written, I thought we'd have to do more work to supply fetchzip, but the next invokation of nix-build seems to call fetchzip without any definition errors so I assume the error is in the documentation.
* show nix-shell --run
it's quite useful and not necessarily obvious without reading reference documentation
Co-authored-by: Silvan Mosberger <github@infinisil.com>
historically it still points to Cachix and not to a community-owned
instance. at the moment there is no regular community newsletter, which
would certainly include updates about documentation. we can add it back
once such a thing exists.
I'm a newbie, so I might be missing something, but the use of an unquoted URL here seems like it goes against the "Best Practice" page (https://nix.dev/guides/best-practices#urls), which says to always quote URLs.
* tutorial: Propagate previous geocode changes
Propagate the changes made in a previous code snippet to this code
snippet. Primarily fixing the poorly referenced ``${geocode``.
* tutorial: Fix requestParams for path.nix
Adjust the functionality to reference geocode correctly and
also to make sure of the correct escaping formats.
Signed-off-by: Brian McGillion <bmg.avoin@gmail.com>
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
* mv question -f faqs -t nix-recipes
* add nix-recipes to page index and fix hierarchy
* change question to statement
* rephrase a few sentences and add links
* move the question to troubleshooting
* fix broken link
---------
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
* shorten the sharing dependencies article to a guide
the contents do not really warrant a full-blown tutorial
* use an example with an explicit build-time dependency
* fix typo
* link `inputsFrom` to Nixpkgs manual
The current code has a number of issues.
1. realising the code results in:
``
markers=$(geocode 'New York') size=640x640 scale=2 zoom=7 ...
^-------------------^ SC2046 (warning): Quote this to prevent
word splitting.
``
2.
``
$(geocode ${lib.escapeShellArg marker.location})"
``
Assumes that geocode has been added to the PATH so replace with
``
${config.scripts.geocode}/bin/geocode
``
as per previous examples.
3.
``
in "markers=${ lib.concatStringsSep "\\|" attributes}";
in builtins.map paramForMarker config.map.markers;
``
The ordering of this actually creates multiple ``[markers =]``
parameters and does not use the concatenation string to join the
attributes together (in effect there is only 1 attribute per call) to
map, and 1 new ``marker`` created.
Signed-off-by: Brian McGillion <bmg.avoin@gmail.com>
* tutorials: fix passing paramaters to geocode
When running the package as-is the following error occurs
``geocode: line 7: $1: unbound``
This is caused because ``scripts.geocode`` does not pass the parameters
down to the wrapped script ``geocode``.
Signed-off-by: Brian McGillion <bmg.avoin@gmail.com>
this is the most cursed setup you will see any time soon.
we're dumping the Nix manual unchanged into the build tree *after*
building. the reason is that we'd want to link to it from our table of
contents, but because Sphinx does not allow adding arbitrary files to
the build output in arbitrary locations (only `_static` works). but we
want to place the manual behind a particular URL, and the alternative of
maintaining URL rewrites (e.g. in nginx) is not accessible here because the
infrastructure is managed somewhere else.
now that the files won't appear in their desired locations at Sphinx
build time, we can't use relative links to reference them, therefore we
have to resort to pointing to the web URL the manual will appear at.
this is terrible and I'm sorry. please fix this if you have a better
idea. once we use URLs though, we have to avoid linkchecking, since
those files may not be there before deploying them.
figuring all of this out took way longer than anyone would wish.
Co-authored-by: Alejandro Sanchez Medina <alejandrosanchzmedina@gmail.com>
* Draft module system introduction tutorial
* add intro/conclusion, rework prose, follow styleguide, clean diffs
* Review pass
* Apply suggestions from code review
* fix whitespace
* add some more motivation the each section
* make scripts downloadable
* address review comments
* make script actually work
...hopefully. can't test it without Google API key
* add file watching
yes, this looks scary, and yes, it works.
* update diff and wording
* more notes on potential pitfalls
* be explicit which `map` we mean
* split nullable from default values
* also wrap the geocode script
* work through the tutorial to the end
* add tutorial overview
* `lib` is always passed
* add separate section for `evalModules` and fix link
* make option strucutre more self-explanatory
* explain command line invocations
* add note on incomplete reference documentation
* add more highlight to the `config` distinction
* fix parameter passing to the `./map` script
* fix typo
* fix wording
* link to summer of nix
* add missing word
* link to Google Maps API docs
* more explicit requirement
* use correct module system terminology
* Update source/tutorials/module-system/module-system.md
* Apply suggestions from code review
* whitespace
* module-system.md: replace comments with captions
* add missing lang for code-block
* Update module system title
* change most headers to be about module features (#797)
* change most headers to be about module features
Some headers could not be made about module features, and that's a
strong signal that those sections should be removed.
* Apply suggestions from code review
* module-system.md: Fix header casing
Co-authored-by: Alexander Groleau <source@proof.construction>
Co-authored-by: asymmetric <lorenzo@mailbox.org>
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
recent additions to the Nix manual clarify the distinction between
search path and lookup path, and also document the resolution algorithm.
lookup paths are now a distinct Nix language construct with its own
reference documentation.
* Remove specific software name from header
There's enough detail about it below, and the specific tech isn't the point of this section anyway.
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
* rewrite guide to pinning dependencies with niv
* use the specific branch directly
Co-authored-by: Silvan Mosberger <github@infinisil.com>
* use the shell's niv explicitly
* Apply suggestions from code review
---------
Co-authored-by: Silvan Mosberger <github@infinisil.com>
This does not yet follow #701, because the change to get there would be
too big. The goal is to keep the table of contents meaningful at all
times and the diff of each pull request manageable.
The packaging tutorial is quite important, so it's not wrong to have it
visible on the front page until we have enough material for a packaging
section.
The sharing dependencies article should really be a very brief guide, but
because that would be quite a big change, it's only moved to the Guides
section for now.
* add Recipes section under Guides category
This also removes the templates section, as we're not maintaining it and it likely won't be necessary anyway once the curriculum is roughly finished.
the instructions say that the command will open a window, which
naturally requires a graphical environment. but this is very late in the
process, and will likely not be obvious in the middle of a a self-directed learning situation.
* move 'are there...impurities in builds?' -f recipes -t concepts
* reword some items and add links/more info
* fix random bullet point
* rm nix hour ref
* rm home directory bullet point
* reword question to make it more specific
* add back filesystem item
* replace passive to keep list's theme
* fix typo
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
* add nix version item to the list
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
* add binfmt to linux kernel items
---------
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
rephrase slightly for brevity and clarity.
re-use the examples from the ad-hoc environment tutorial both for
simplicity as well as to give it some continuity.
Co-authored-by: Alexander Groleau <alex@proof.construction>
remove references to "towards reproducibility" as that's not very
focused, and at that point readers will likely be familiar with the
concept such that they only need the reference, if anything
this fits the global outline we developed, and also makes the tutorial
more immediately visible - working with the Nix language is a core skill
we want to teach after all
