Merge pull request #272183 from infinisil/nixpkgs-reference

doc: Rename to Nixpkgs reference manual and restate purpose

doc/README.md

@@ -1,14 +1,18 @@
-# Contributing to the Nixpkgs manual
+# Contributing to the Nixpkgs reference manual
 
-This directory houses the sources files for the Nixpkgs manual.
+This directory houses the sources files for the Nixpkgs reference manual.
+
+Going forward, it should only contain [reference](https://nix.dev/contributing/documentation/diataxis#reference) documentation.
+For tutorials, guides and explanations, contribute to <https://nix.dev/> instead.
+
+For documentation only relevant for contributors, use Markdown files and code comments in the source code.
+
+Rendered documentation:
+- [Unstable (from master)](https://nixos.org/manual/nixpkgs/unstable/)
+- [Stable (from latest release)](https://nixos.org/manual/nixpkgs/stable/)
 
-You can find the [rendered documentation for Nixpkgs `unstable` on nixos.org](https://nixos.org/manual/nixpkgs/unstable/).
 The rendering tool is [nixos-render-docs](../pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs), sometimes abbreviated `nrd`.
 
-[Docs for Nixpkgs stable](https://nixos.org/manual/nixpkgs/stable/) are also available.
-
-If you're only getting started with Nix, go to [nixos.org/learn](https://nixos.org/learn).
-
 ## Contributing to this documentation
 
 You can quickly check your edits with `nix-build`:

doc/manual.md.in

@@ -1,4 +1,4 @@
-# Nixpkgs Manual {#nixpkgs-manual}
+# Nixpkgs Reference Manual {#nixpkgs-manual}
 ## Version @MANUAL_VERSION@
 
 ```{=include=} chapters

doc/preface.chapter.md

@@ -6,11 +6,15 @@ The Nix Packages collection (Nixpkgs) is a set of thousands of packages for the
 Packages are available for several platforms, and can be used with the Nix
 package manager on most GNU/Linux distributions as well as [NixOS](https://nixos.org/nixos).
 
-This manual primarily describes how to write packages for the Nix Packages collection
-(Nixpkgs). Thus it’s mainly for packagers and developers who want to add packages to
-Nixpkgs. If you like to learn more about the Nix package manager and the Nix
-expression language, then you are kindly referred to the [Nix manual](https://nixos.org/nix/manual/).
-The NixOS distribution is documented in the [NixOS manual](https://nixos.org/nixos/manual/).
+This document is the user [_reference_](https://nix.dev/contributing/documentation/diataxis#reference) manual for Nixpkgs.
+It describes entire public interface of Nixpkgs in a concise and orderly manner, and all relevant behaviors, with examples and cross-references.
+
+To discover other kinds of documentation:
+- [nix.dev](https://nix.dev/): Tutorials and guides for getting things done with Nix
+- [NixOS **Option Search**](https://search.nixos.org/options) and reference documentation
+- [Nixpkgs **Package Search**](https://search.nixos.org/packages)
+- [**NixOS** manual](https://nixos.org/manual/nixos/stable/): Reference documentation for the NixOS Linux distribution
+- [`CONTRIBUTING.md`](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md): Contributing to Nixpkgs, including this manual
 
 ## Overview of Nixpkgs {#overview-of-nixpkgs}
 

lib/README.md

@@ -42,7 +42,7 @@ Reference documentation for library functions is written above each function as
 These comments are processed using [nixdoc](https://github.com/nix-community/nixdoc) and [rendered in the Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/#chap-functions).
 The nixdoc README describes the [comment format](https://github.com/nix-community/nixdoc#comment-format).
 
-See the [chapter on contributing to the Nixpkgs manual](https://nixos.org/manual/nixpkgs/#chap-contributing) for how to build the manual.
+See [doc/README.md](../doc/README.md) for how to build the manual.
 
 ## Running tests