From 32751beeeb8cd89f881843a9880e53b914aa1f5e Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sun, 12 Jul 2026 20:52:43 +0200 Subject: [PATCH] doc/readme: tidy up meta commentary meta-commentary is discouraged as per doc/styleguide.md --- doc/README.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/doc/README.md b/doc/README.md index 49ab93677d73..14de0dd2651b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -14,17 +14,12 @@ Use **examples** first to show how to get something done. Keep **Explanation** l Use our [styleguide](./styleguide.md) for more in depth guidance on writing good documentation. -This directory contains **guides** and **reference** documentation for Nixpkgs. +Documentation about Nixpkgs belongs here, this includes 'getting-started'-guides and 'onboarding-guides' for *using* Nixpkgs and the language frameworks it ships. -Borrowing from [Diátaxis framework](https://diataxis.fr/) what suits our needs: +Write **guides** task-first: lead with a working example, then explain in prose. +Write **reference** as the specification of functions and attributes. -**Guides** are task-oriented. They can be tutorial-style walkthroughs or how-to sections. -Explanations appear as prose after examples. - -**Reference** documentation is the specification of functions and attributes. - -We are actively working to generate **all** reference documentation from the [doc-comments](https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md) present in code. -This also provides the benefit of using `:doc` in the `nix repl` to view reference documentation locally on the fly. +We are actively working to generate reference documentation from the [doc-comments](https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md) present in code, which also lets you view it locally with `:doc` in `nix repl`. See [Document structure](#document-structure) for a structural template.