During NixCon 2019, a group of us met to discuss Nix’s documentation status and
The notes for this discussion were recorded:
We chose the following items as our top priorities:
Write an RFC to create a doc team that is responsible for – and can make decisions about – the website.
Prototype a documentation standard on top of the Flake RFC.
Don’t try to expand the scope of the Flake RFC.
Don’t necessarily create a documentation RFC yet.
Just make sure there are no major blockers to a standardized doc format.
Manuals should reference each other at the beginning
This is a small item to add some text at the beginning of each document (Nix,
NixOS, Nixpkgs). They should each explain what the reader will find in the
document, and where to go for other parts of the system.
E.g., “This document is about the Nix language, for foo go to manual bar”.
This is a big item, so we should break it down further.
The vision is to have a “book” like the rust book for newcomers to start from
scratch, learn fundamental concepts, and gain familiarity with the language and
Prototype a website structure
The goal is a new layout of the top-level information available on the website.
For instance, the “Community” and “Support” sections currently have a mix of
overlapping information that could be better organized and named.
We can do this as a prototype and build on https://builtwithnix.org/.
Move instructions on how to edit documentation closer to the top
This is a small item. The manuals have sections on how to edit their content,
but they are small and dissimilar. They could be made uniform and more visible.
Move installation section out of nix/nixos manual
Installation instructions are good for tutorials and learning guides, but they
are out of place in a language reference.
Merge nix and nixpkgs manuals
This is a big item. You would not want to simply concatenate the manuals, but
curate and merge sensibly.
The motivation for this change is that most languages do this, and we would have
one place to search. Never look for builtins in the wrong place again!