Style guide#

This document outlines the guidelines we use when writing documentation.

Writing style#

Aim for clarity and brevity#

I would have written a shorter letter, but I did not have the time.

— Blaise Pascal

Readers’ time and attention is limited. Take the time to be extraordinarily respectful with their cognitive resources.

The same holds for communication directed to contributors and maintainers: This is a public project, and many people will read what you write. Use this leverage with care.

  • Follow the evidence-based plain language guidelines.

    • Don’t use jargon. Readers may not be familiar with particular technical terms.

    • Don’t use long, complicated words if there are shorter, simpler words that convey the same meaning.

  • Use the imperative voice when giving instructions. For example, write:

    Add the python310 package to buildInputs.

    Don’t use a conversational tone, as it distracts from the contents. For example, don’t write:

    Going forward, let’s now add the python310 package to buildInputs as we have seen in the previous tutorial.

Use inclusive language#

Adapted from Contributor Covenant and The Carpentries Code of Conduct:

  • Use welcoming and inclusive language

  • Show empathy and respect towards other people

  • Be respectful of different viewpoints and experiences

  • Give and gracefully accept constructive criticism

  • Focus on what is best for the community

Avoid idioms as they can be hard to understand for non-native English speakers.

Don’t try to be funny. Humor is highly culturally sensitive. At best, jokes may obfuscate the relevant instructions. At worst, jokes may offend readers and invalidate our effort to help them learn.

Don’t use references to popular culture. What you may consider well-known may be entirely obscure and distracting to people from different backgrounds.

Voice#

Describe the subject factually and use the imperative voice in direct instructions.

Do not assume a personal relationship with readers, prefer clarity and brevity to emotional appeal.

Use second person (“you”) to refer to the reader and only use “we” to refer to the Nix Community.

Be correct, cite sources#

The only thing worse than no documentation is incorrect documentation. One way to ensure correctness is by citing your sources. If you make a claim about how something works (e.g. that a command line argument exists), link to official documentation for that subject. We would like to maintain a network of documentation, so linking to other documentation helps to reinforce the documentation ecosystem.

It is explicitly encouraged to update or restructure the manuals where appropriate, to improve the overall experience.

Markup and source#

Code samples#

At the bare minimum code samples that are intended to work should work.

If you are going to present an example that does not work (e.g. you’re illustrating a common mistake) explain so beforehand. Many readers will get stuck trying to make example code work without reading ahead to find out that the code isn’t intended to work.

Code samples should all include a programming language when applicable for syntax highlighting when rendered e.g.

```python
print("Hello, World!")
```

Headers#

Reserve the largest header (#) for the title.

Use Markdown headers ## through #### to divide up content in the body of the document, but prefer to stay in the ##-### range. Finer grained headings are not necessarily better.

One line per sentence#

Write one sentence per line. This makes review easier since the git diffs are line-oriented and the smallest level of granularity in the GitHub review interface is a line of text.