Merge pull request #9017 from fricklerhandwerk/contributing-docs

add contributing guide for documentation

doc/manual/local.mk

@@ -173,6 +173,10 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
 	done
 	@touch $@
 
+# the `! -name 'contributing.md'` filter excludes the one place where
+# `@docroot@` is to be preserved for documenting the mechanism
+# FIXME: maybe contributing guides should live right next to the code
+# instead of in the manual
 $(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md
 	$(trace-gen) \
 		tmp="$$(mktemp -d)"; \
@@ -180,7 +184,7 @@ $(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/
 		find "$$tmp" -name '*.md' | while read -r file; do \
 			$(call process-includes,$$file,$$file); \
 		done; \
-		find "$$tmp" -name '*.md' | while read -r file; do \
+		find "$$tmp" -name '*.md' ! -name 'documentation.md' | while read -r file; do \
 			docroot="$$(realpath --relative-to="$$(dirname "$$file")" $$tmp/manual/src)"; \
 			sed -i "s,@docroot@,$$docroot,g" "$$file"; \
 		done; \

doc/manual/src/SUMMARY.md.in

@@ -106,6 +106,7 @@
 - [Contributing](contributing/contributing.md)
   - [Hacking](contributing/hacking.md)
   - [Testing](contributing/testing.md)
+  - [Documentation](contributing/documentation.md)
   - [Experimental Features](contributing/experimental-features.md)
   - [CLI guideline](contributing/cli-guideline.md)
   - [C++ style guide](contributing/cxx.md)

doc/manual/src/contributing/contributing.md

@@ -1 +1,8 @@
-# Contributing
+# Development
+
+Nix is developed on GitHub.
+Check the [contributing guide](https://github.com/NixOS/nix/blob/master/CONTRIBUTING.md) if you want to get involved.
+
+This chapter is a collection of guides for making changes to the code and documentation.
+
+If you're not sure where to start, try to [compile Nix from source](./hacking.md) and consider [making improvements to documentation](./documentation.md).

doc/manual/src/contributing/documentation.md

@@ -0,0 +1,181 @@
+# Contributing documentation
+
+Improvements to documentation are very much appreciated, and a good way to start out with contributing to Nix.
+
+This is how you can help:
+- Address [open issues with documentation](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation)
+- Review [pull requests concerning documentation](https://github.com/NixOS/nix/pulls?q=is%3Apr+is%3Aopen+label%3Adocumentation)
+
+Incremental refactorings of the documentation build setup to make it faster or easier to understand and maintain are also welcome.
+
+## Building the manual
+
+Build the manual from scratch:
+
+```console
+nix-build $(nix-instantiate)'!doc'
+```
+
+or
+
+```console
+nix build .#^doc
+```
+
+and open `./result-doc/share/doc/nix/manual/index.html`.
+
+To build the manual incrementally, [enter the development shell](./hacking.md) and run:
+
+```console
+make manual-html -j $NIX_BUILD_CORES
+```
+
+and open `./outputs/out/share/doc/nix/manual/language/index.html`.
+
+In order to reflect changes to the [Makefile for the manual], clear all generated files before re-building:
+
+[Makefile for the manual]: https://github.com/NixOS/nix/blob/master/doc/manual/local.mk
+
+```console
+rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make manual-html -j $NIX_BUILD_CORES
+```
+
+## Style guide
+
+The goal of this style guide is to make it such that
+- The manual is easy to search and skim for relevant information
+- Documentation sources are easy to edit
+- Changes to documentation are easy to review
+
+You will notice that this is not implemented consistently yet.
+Please follow the guide when making additions or changes to existing documentation.
+Do not make sweeping changes, unless they are programmatic and can be validated easily.
+
+### Language
+
+This manual is [reference documentation](https://diataxis.fr/reference/).
+The typical usage pattern is to look up isolated pieces of information.
+It should therefore aim to be correct, consistent, complete, and easy to navigate at a glance.
+
+- Aim for clarity and brevity.
+
+  Please take the time to read the [plain language guidelines](https://www.plainlanguage.gov/guidelines/) for details.
+
+- Describe the subject factually.
+
+  In particular, do not make value judgements or recommendations.
+  Check the code or add tests if in doubt.
+
+- Provide complete, minimal examples, and explain them.
+
+  Readers should be able to try examples verbatim and get the same results as shown in the manual.
+  Always describe in words what a given example does.
+
+  Non-trivial examples may need additional explanation, especially if they use concepts from outside the given context.
+
+- Use British English.
+
+  This is a somewhat arbitrary choice to force consistency, and accounts for the fact that a majority of Nix users and developers are from Europe.
+
+### Links and anchors
+
+Reference documentation must be readable in arbitrary order.
+Readers cannot be expected to have any particular prerequisite knowledge about Nix.
+While the table of contents can provide guidance and full-text search can help, they are most likely to find what they need by following sensible cross-references.
+
+- Link to technical terms
+
+  When mentioning Nix-specific concepts, commands, options, settings, etc., link to appropriate documentation.
+  Also link to external tools or concepts, especially if their meaning may be ambiguous.
+  You may also want to link to definitions of less common technical terms.
+
+  Then readers won't have to actively search for definitions and are more likely to discover relevant information on their own.
+
+  > **Note**
+  >
+  > `man` and `--help` pages don't display links.
+  > Use appropriate link texts such that readers of terminal output can infer search terms.
+
+- Do not break existing URLs between releases.
+
+  There are countless links in the wild pointing to old versions of the manual.
+  We want people to find up-to-date documentation when following popular advice.
+
+  - When moving files, update [redirects on nixos.org](https://github.com/NixOS/nixos-homepage/blob/master/netlify.toml).
+
+    This is especially important when moving information out of the Nix manual to other resources.
+
+  - When changing anchors, update [client-side redirects](https://github.com/NixOS/nix/blob/master/doc/manual/redirects.js)
+
+  The current setup is cumbersome, and help making better automation is appreciated.
+
+The build checks for broken internal links with.
+This happens late in the process, so [building the whole manual](#building-the-manual) is not suitable for iterating quickly.
+[`mdbook-linkcheck`] does not implement checking [URI fragments] yet.
+
+[`mdbook-linkcheck`]: https://github.com/Michael-F-Bryan/mdbook-linkcheck
+[URI fragments]: https://en.wikipedia.org/wiki/URI_fragment
+
+### Markdown conventions
+
+The manual is written in markdown, and rendered with [mdBook](https://github.com/rust-lang/mdBook) for the web and with [lowdown](https://github.com/kristapsdz/lowdown) for `man` pages and `--help` output.
+
+For supported markdown features, refer to:
+- [mdBook documentation](https://rust-lang.github.io/mdBook/format/markdown.html)
+- [lowdown documentation](https://kristaps.bsd.lv/lowdown/)
+
+Please observe these guidelines to ease reviews:
+
+- Write one sentence per line.
+
+  This makes long sentences immediately visible, and makes it easier to review changes and make direct suggestions.
+
+- Use reference links – sparingly – to ease source readability.
+  Put definitions close to their first use.
+
+  Example:
+
+  ```
+  A [store object] contains a [file system object] and [references] to other store objects.
+
+  [store object]: @docroot@/glossary.md#gloss-store-object
+  [file system object]: @docroot@/architecture/file-system-object.md
+  [references]: @docroot@/glossary.md#gloss-reference
+  ```
+
+- Use admonitions of the following form:
+
+  ```
+  > **Note**
+  >
+  > This is a note.
+  ```
+
+### The `@docroot@` variable
+
+`@docroot@` provides a base path for links that occur in reusable snippets or other documentation that doesn't have a base path of its own.
+
+If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/src` directory.
+
+If the `@docroot@` literal appears in an error message from the [`mdbook-linkcheck`] tool, the `@docroot@` replacement needs to be applied to the generated source file that mentions it.
+See existing `@docroot@` logic in the [Makefile for the manual].
+Regular markdown files used for the manual have a base path of their own and they can use relative paths instead of `@docroot@`.
+
+## API documentation
+
+[Doxygen API documentation] is available online.
+You can also build and view it yourself:
+
+[Doxygen API documentation]: https://hydra.nixos.org/job/nix/master/internal-api-docs/latest/download-by-type/doc/internal-api-docs
+
+```console
+# nix build .#hydraJobs.internal-api-docs
+# xdg-open ./result/share/doc/nix/internal-api/html/index.html
+```
+
+or inside `nix-shell` or `nix develop`:
+
+```
+# make internal-api-html
+# xdg-open ./outputs/doc/share/doc/nix/internal-api/html/index.html
+```

doc/manual/src/contributing/hacking.md

@@ -220,54 +220,3 @@ Configure your editor to use the `clangd` from the shell, either by running it i
 > For some editors (e.g. Visual Studio Code), you may need to install a [special extension](https://open-vsx.org/extension/llvm-vs-code-extensions/vscode-clangd) for the editor to interact with `clangd`.
 > Some other editors (e.g. Emacs, Vim) need a plugin to support LSP servers in general (e.g. [lsp-mode](https://github.com/emacs-lsp/lsp-mode) for Emacs and [vim-lsp](https://github.com/prabirshrestha/vim-lsp) for vim).
 > Editor-specific setup is typically opinionated, so we will not cover it here in more detail.
-
-### Checking links in the manual
-
-The build checks for broken internal links.
-This happens late in the process, so `nix build` is not suitable for iterating.
-To build the manual incrementally, run:
-
-```console
-make manual-html -j $NIX_BUILD_CORES
-```
-
-In order to reflect changes to the [Makefile], clear all generated files before re-building:
-
-[Makefile]: https://github.com/NixOS/nix/blob/master/doc/manual/local.mk
-
-```console
-rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make html -j $NIX_BUILD_CORES
-```
-
-[`mdbook-linkcheck`] does not implement checking [URI fragments] yet.
-
-[`mdbook-linkcheck`]: https://github.com/Michael-F-Bryan/mdbook-linkcheck
-[URI fragments]: https://en.wikipedia.org/wiki/URI_fragment
-
-#### `@docroot@` variable
-
-`@docroot@` provides a base path for links that occur in reusable snippets or other documentation that doesn't have a base path of its own.
-
-If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/src` directory.
-
-If the `@docroot@` literal appears in an error message from the `mdbook-linkcheck` tool, the `@docroot@` replacement needs to be applied to the generated source file that mentions it.
-See existing `@docroot@` logic in the [Makefile].
-Regular markdown files used for the manual have a base path of their own and they can use relative paths instead of `@docroot@`.
-
-## API documentation
-
-Doxygen API documentation is [available
-online](https://hydra.nixos.org/job/nix/master/internal-api-docs/latest/download-by-type/doc/internal-api-docs). You
-can also build and view it yourself:
-
-```console
-# nix build .#hydraJobs.internal-api-docs
-# xdg-open ./result/share/doc/nix/internal-api/html/index.html
-```
-
-or inside a `nix develop` shell by running:
-
-```
-# make internal-api-html
-# xdg-open ./outputs/doc/share/doc/nix/internal-api/html/index.html
-```