diff --git a/doc/README.md b/doc/README.md index 211f986b851d..534fc92de5a8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -2,10 +2,20 @@ 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 instead. +> [!IMPORTANT] +> We are actively restructuring our documentation to follow the [Diátaxis framework](https://diataxis.fr/) +> +> Going forward, this directory should **only** contain [reference documentation](https://nix.dev/contributing/documentation/diataxis#reference). +> For tutorials, guides and explanations, contribute to instead. +> +> 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. -For documentation only relevant for contributors, use Markdown files and code comments in the source code. +For documentation only relevant for contributors, use Markdown files next to the source and regular code comments. + +> [!TIP] +> Feedback for improving support for parsing and rendering doc-comments is highly appreciated. +> [Open an issue](https://github.com/NixOS/nixpkgs/issues/new?labels=6.topic%3A+documentation&title=Doc%3A+) to request bugfixes or new features. Rendered documentation: - [Unstable (from master)](https://nixos.org/manual/nixpkgs/unstable/)