nixpkgs/doc/styleguide.md

Styleguide

Writing Principles

A consistent style greatly increases the usability of all documentation and communication.

Use this page as a reference and style guide for our internal and external documentation.

Knowledge Expectations

Assume competence, not familiarity.

Write for someone who knows a great deal — up to but not including this project.

What readers know:

• Basic computer operation
• Command line familiarity
• General interest in systems configuration

What readers don't know:

• NixOS-specific concepts
• NixOS ecosystem details or grammar
• NixOS workflows

If specific knowledge is required, mention it at the start of the page.

Show, Don't Tell

The fastest path to understanding is a working example. People learn by doing, not by reading about doing.

Recommended structure:

• Start with the minimal working code or command
• Briefly explain what it does
• Cover edge cases or variations
• Link to further information instead of including it

Grammar and Style

Sentence structure:

• Use simple, direct sentences
• Break complex ideas into multiple short sentences
• Avoid nested clauses

Bad:

The following command, which utilizes nixos-generate-config to produce a comprehensive hardware configuration, will write the results back into the respective configuration directory located on your local machine.

What the user does is hidden in the middle. nixos-generate-config is a leaked implementation detail. Users care about detecting hardware, not the tool that does it.

Good:

This command detects your hardware and saves the configuration.

Content Organization

Lead with value. State what the reader will accomplish before explaining how.

Bad:

To create a new NixOS configuration that you can later use as a webserver, first navigate to your project directory, then add a new host configuration file with the desired machine name.

Good:

Add a webserver configuration to your NixOS setup:

# hosts/webserver/configuration.nix
{ ... }:
{
  services.nginx.enable = true;
}

Use progressive disclosure. Introduce concepts only when needed.

Recommended structure:

1. State the goal (one sentence)
2. Show the simplest working example
3. Explain concepts if needed
4. Provide advanced options separately or link to the reference

No Meta-commentary

Don't describe what the documentation does. Just do it.

Don't:

This section explains how to configure networking. The following guide walks you through setting up a web server.

Do:

Configure networking by setting: Set up a web server:

Code Examples

Keep examples focused:

• Show one concept at a time
• Use realistic but simple scenarios
• Avoid dependencies on other examples

Minimal comments

Let the code speak for itself. Paste code examples directly and without further alteration.

Bad:

# This sets the hostname for the machine
{
  networking.hostName = "webserver"; # Change this to your machine's hostname
  # This enables SSH access
  services.openssh.enable = true; # Required for remote deployment
}

Good:

{
  networking.hostName = "webserver";
  services.openssh.enable = true;
}

Lead with Practical Examples

Don't front-load theory. Readers want to accomplish something first, then understand why it works.

• Show configuration as what you want, not how the module system works
• Introduce Nix-specific concepts only when they are needed to complete the task
• Defer language mechanics to reference pages or nix.dev

Bad:

Before adding a service, you need to understand the NixOS module system and attribute set merging.

Good:

Enable nginx:

{ services.nginx.enable = true; }

This adds nginx to your system configuration. Rebuild to apply:

sudo nixos-rebuild switch

Teach Nix through examples, not theory

Users learn the NixOS module system by seeing patterns first.

• Start with a working example
• Explanation follows the code
• Link deeper concepts instead of inlining them
• Link to nix.dev for optional learning

General Rules

• Abbreviate keys like ssh-ed25519 AAAAC3NzaC…
• Abbreviate IP addresses like 192.168.XXX.XXX
• Variables are capitalized and start with $, e.g. $YOUR_HOSTNAME
• Variables should be directly usable during copy-paste
• Do not describe missing code parts (#elided, #omitted)
• Machine vs Host: use "machine" for the NixOS system identity, "host" for the physical or virtual hardware

Capitalization

• GB / RAM / HDD
• bootable USB drive
• Wi-Fi / DHCP / DNS
• macOS / NixOS / Nix / Linux
• Flakes
• git

Headings

Use sentence case. A reader scanning only headings should understand the page.

Don't:

Getting Started Overview Configure The Database

Do:

Set up a PostgreSQL database Configure networking Add a user to the system

Imperative Mood, Voice, and Person

Use imperative mood for instructions. Address the reader as "you", not "the user". Use active voice; in other words, make the subject do the action.

Don't:

The user should run the following command. The configuration will need to be updated. The key is generated by the system.

Do:

Run the command. Update the configuration. The system generates the key.

Tense

Use present tense for descriptions. Future tense makes documentation feel tentative.

Don't:

This will create a new folder. Running this command will install the package.

Do:

This creates a new folder. Running this command installs the package.

Be Confident

State facts. Don't hedge with "should," "might," "typically," or "usually" unless the behavior genuinely varies.

Don't:

This should create the configuration file. The service will usually start automatically.

Do:

This creates the configuration file. The service starts automatically.

Avoid Nominalizations

A nominalization is a verb turned into a noun, often by adding -tion, -meant, or -ance (e.g. "explanation", "selection"). The fix: find the hidden verb and use it directly.

Don't:

Make a selection from the list. Provide an explanation of the error.

Do:

Select from the list. Explain the error.

Plain Words

Technical precision for technical terms; plain language for everything else.

• "use" not "utilize"
• "start" not "initiate"
• "end" not "terminate"
• "help" not "facilitate"
• "send" not "transmit"
• "set up" not "establish"
• "find out" not "ascertain"

Filler Words and Weak Phrases

Cut words and phrases that add length without meaning.

Delete on sight:

• "simply", "just", "easily", "basically", "obviously"
• "in order to" → use "to"
• "allows you to" → use the verb directly
• "it's worth noting that" → just say the thing
• no exclamation marks in technical prose

Don't:

Simply run nixos-rebuild switch. In order to deploy, you first need to run the command, which allows you to push the config. It's worth noting that this requires root access.

Do:

Run nixos-rebuild switch. To deploy, run: This requires root access.

Every word must earn its place.

Writing Procedures

One instruction per sentence. Don't pack multiple actions into one sentence.

Don't:

Navigate to your project directory and run the command, then check the output.

Do:

1. Navigate to your project directory.
2. Run the command.
3. Check the output.

Don't bury the negative. Key limitations should be prominent, not a footnote after a positive description.

Don't:

This service supports multiple roles, integrates with existing modules, and works great for most setups (note that multiple instances are not supported).

Do:

This service does not support multiple instances.

Consistent Terminology

Pick a term and stick to it. Don't swap synonyms to avoid repetition. In technical documentation, repetition is clarity.

Don't:

Create a machine... configure the host... deploy the node.

Do:

Create a machine... configure the machine... deploy the machine.

Links

Use descriptive link text. Never use "click here" or "this link."

Don't:

For more information, see [this page](url). Click [here](url) to read the reference.

Do:

See the [NixOS options reference](url) for details. Read the [NixOS module system guide](url).

Only link when the destination is directly relevant, not for generic background context (sometimes known as "Wikipedia-style links"). Readers feel obligated to click links, fearing they'll miss something important. Don't send them to a generic article about a technology when they're looking for how your system uses it.

Don't:

Our software uses SQLite for storage. (Reader clicks expecting schema details — finds a generic product page instead.)

(Note that in the above example, the SQLite link is the SQLite home page, which is likely not pertinent.)

Do:

See [database schema](url) for the full table structure.

UI Language

Match UI element names exactly: wording, casing, and spacing (even if a label seems oddly worded).

Don't:

Click the generator button. Select the save option.

Do:

Click Generate a Key. Click Save Changes.

Someone will go looking for a button labeled "generator." They will not find it. They will be frustrated.

Consistency between documentation and interface builds confidence. Words are part of the interface.

:::{.tip} This can be tricky as UI changes; we don't yet have a policy in place for how to handle this. We welcome comments and suggestions. :::

Clean system discipline

Your machine has things new users don't: cached credentials, installed tools, environment variables, existing configuration. When writing or updating documentation:

Don't:

Write steps from memory on your development machine, assuming what works there will work everywhere.

Do:

• Start on a clean system — a fresh VM or new user account
• Take notes in real time as you work through the steps
• Document every warning, prompt, or unexpected output the system shows

Also think in combinations: WSL vs native Linux, with and without existing keys. You don't need to test every matrix square — but you need to know which ones diverge.

Never type code — always copy-paste

Always copy commands and code from a terminal where you just ran them successfully. Never retype from memory.

Don't:

Retype a command from memory into the documentation. Retype code into a code-block from memory

Do:

Paste commands directly from the shell or IDE. Paste code that has been successfully validated with nix-instantiate or nix-build

Replace sensitive values with placeholders: <YOUR-KEY>, <YOUR-HOST>, <YOUR-TOKEN>.

Typed-from-memory commands introduce subtle errors. Even the most experienced software developers have occasional typos.