Merge pull request #272183 from infinisil/nixpkgs-reference

doc: Rename to Nixpkgs reference manual and restate purpose

4 files changed, 21 insertions, 13 deletions

diff --git a/doc/README.md b/doc/README.md
index e9f2a53c355d..616409beaaf5 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -1,13 +1,17 @@
-# 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.
 
-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`.
+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.
 
-[Docs for Nixpkgs stable](https://nixos.org/manual/nixpkgs/stable/) are also available.
+Rendered documentation:
+- [Unstable (from master)](https://nixos.org/manual/nixpkgs/unstable/)
+- [Stable (from latest release)](https://nixos.org/manual/nixpkgs/stable/)
 
-If you're only getting started with Nix, go to [nixos.org/learn](https://nixos.org/learn).
+The rendering tool is [nixos-render-docs](../pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs), sometimes abbreviated `nrd`.
 
 ## Contributing to this documentation
 
diff --git a/doc/manual.md.in b/doc/manual.md.in
index 52971ff526c2..642247e16612 100644
--- a/doc/manual.md.in
+++ b/doc/manual.md.in
@@ -1,4 +1,4 @@
-# Nixpkgs Manual {#nixpkgs-manual}
+# Nixpkgs Reference Manual {#nixpkgs-manual}
 ## Version @MANUAL_VERSION@
 
 ```{=include=} chapters
diff --git a/doc/preface.chapter.md b/doc/preface.chapter.md
index aa6acca1217a..93cd1a00b4f2 100644
--- a/doc/preface.chapter.md
+++ b/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}
 
diff --git a/lib/README.md b/lib/README.md
index 220940bc2122..a886cf5bfb55 100644
--- a/lib/README.md
+++ b/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