# 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 -E '(import ./.).packages.${builtins.currentSystem}.nix.doc'
```

or

```console
nix build .#nix-manual
```

and open `./result/share/doc/nix/manual/index.html`.


To build the manual incrementally, [enter the development shell](./building.md) and run:

```console
make manual-html-open -j $NIX_BUILD_CORES
```

In order to reflect changes to the [Makefile for the manual], clear all generated files before re-building:


```console
rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/source/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.

- Always explain code examples in the text.

  Use comments in code samples very sparingly, for instance to highlight a particular aspect.
  Readers tend to glance over large amounts of code when scanning for information.

  Especially beginners will likely find reading more complex-looking code strenuous and may therefore avoid it altogether.

  If a code sample appears to require a lot of inline explanation, consider replacing it with a simpler one.
  If that's not possible, break the example down into multiple parts, explain them separately, and then show the combined result at the end.
  This should be a last resort, as that would amount to writing a [tutorial](https://diataxis.fr/tutorials/) on the given subject.

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