nathan/nixpkgs
1
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2026-08-25 17:55:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc/readme: tidy up meta commentary (#541150)

Browse Source
This commit is contained in:
Johannes Kirschbauer
2026-08-10 08:04:26 +00:00
committed by GitHub
parent 3bb67c0392 32751beeeb
commit cf50151f15
1 changed files with 4 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
doc/README.md
View File

@@ -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.