One portal for NixOS documentation: the docs team vision

Announcements
1

Documentation for the Nix ecosystem is scattered across components, websites, blog posts, and wiki pages. Users ask “how do I run nginx on NixOS?” and end up stitching together answers from three different sources. When you do find the right manual, it’s a monolithic page where the only navigation strategy is Ctrl-F.

NixOS can be straightforward once you understand the model. That understanding should be built from documentation, not requiring a person in a chat room.

The documentation team has published a vision document to fix this. Here is the short version.

What we want

A single authoritative portal at docs.nixos.org that provides:

  • Clear separation of reference docs and guides
  • Content organized by component, with explicit ownership
  • One page per topic instead of monolithic manuals
  • Cross-component search: query services.postgresql and find matching options, related packages, and relevant guides

Reference documentation is generated from source where possible. Guides are concise and opinionated.

The wiki remains the place for niche topics and experiments. When a wiki page gets linked often enough that it’s clearly load-bearing, it should move into docs.nixos.org. How exactly that promotion happens is still being worked out, input welcome.

Getting started guides are a priority

The first concrete deliverable is a small set of workflows for newcomers:

  • Installing NixOS (end to end)
  • Adding packages and services
  • Upgrading and recovering a system

If you’ve onboarded someone onto NixOS recently and remember where they got stuck, that’s exactly the kind of input we need.

How to contribute

We are still in the early stages: the vision sets the direction, but we need a roadmap which is still taking shape. The immediate priorities are framework evaluation and planning how to migrate content into a multi-page structure at docs.nixos.org.

What’s most useful right now:

  • Feedback on the vision document (as issues or PRs)
  • Input on what content to tackle first and in what order
  • Experience reports from recent or ongoing NixOS onboarding

For context, the documentation we’ll be drawing from currently lives across several repos:

We’ll post regular updates in the Documentation category. We’ll be announcing regular office hours shortly and opening the team for applications.

Signed: The NixOS Documentation Team, ( @hsjobeki, @friedow , @wamirez )

77 Likes
2

Great to see plans to improve documentation story :heart:

So the plan is for the wiki to stay, but what about nix.dev? Will it stay as a tutorial for nixlang or become a redirect to docs.nixos.org?

3

Pardon my skepticism, I’m also for a big docs reform in the ecosystem, but how will docs.nixos.org/wiki.nixos.org avoid becoming yet another competing standard?? Since all of these docs sources exist already, adding another seems to make the field even more fragmented?

8 Likes
4

@bartbie The move from nix.dev isn’t finally decided yet, but the goal is consolidation. If that means nix.dev becomes a redirect, so be it. Content won’t live in two places.

@dtomvan Fair concern, and exactly the risk we’ve noted. As content moves into docs.nixos.org, corresponding sections in the component manuals get replaced with redirects and eventually fully absorbed. Let’s make sure it doesn’t become yet another standard :wink:

6 Likes
5

search.nixos.org would be replaced as well?

2 Likes
6

Amazing idea. I’m all for centralized documentation! Will https://noogle.dev be part of this as well?

1 Like
7

I don’t think all documentation need to live together. In a sense, many different sites with documentation is a sign of strength and vitality. Popular topics have many books written about them. They can evolve on their own terms, with their own voice, for their particular audience and so on.

But documentation should be internally coherent. What it aims to describe, it should do so well.

I noticed this in the vision:

What success looks like

  • You can find all relevant information in one place

I think this has higher chance of success:

  • You can find all relevant information from one place
1 Like
8

As someone that worked on the documentation in the past, I wish you the best. It’s a big task :slight_smile:

My first question is whether “One portal for NixOS documentation” strictly refers to NixOS, or to Nix as a whole. From my time working on the documentation, one of the main struggles was identifying the audience:

  • Developers that want to use Nix for developer tooling, packaging, etc
  • “Everyone else” that wants to learn Nix because it’s required for configuring a NixOS system

The entrypoint for those two groups aren’t the same, and they’re likely to run into different problems:

  • Developer: “why isn’t libfoo in my library path?”
  • NixOS enjoyer: “how do I make sure $SECRET is on this machine and not in the store?”

Otherwise, I’m 100% behind the idea of consolidating the documentation and breaking the manuals up into individual pages rather than the beasts that they are today. My other recommendation on that front is to be wary of sinking a ton of time into trying to make the code snippets testable, it makes the markdown harder to write, and I suspect your first bottleneck will be getting contributors :slight_smile:

I don’t think all documentation need to live together.

I agree that all of the source doesn’t need to live in the same repository. For example, the Nixpkgs manual probably shouldn’t live in the nix repo or vice versa.

In a sense, many different sites with documentation is a sign of strength and vitality.

I think this could be true if the documentation ecosystem was generally healthy and the external documentation sources were complimenting the first-party documentation. They shouldn’t be filling a gap in the first-party documentation. I personally don’t find it a sign of strength and vitality when a single project sends me to multiple websites to learn how it works.

9 Likes
9

Thank Christ.

Good work y’all.

10

Thank you all for the thoughtful replies :folded_hands:

The question about monolithic documentation is, for us, primarily about user experience and information presentation. With “one place” we mean comprehensive, coherent, extensively cross-linked presentation to the reader.

Where the source lives is a separate question, but it matters too. Keeping docs in sync with the code they describe is a problem as of today, and there are tradeoffs from different angles. We’re still figuring this out.

One thing we want to try soon: adding a doc label and/or CODEOWNERS entries for doc paths in nixpkgs so docs PRs actually reach people who can review them. Right now they just get buried in version bump PRs. That would also give us some data on whether a doc contribution workflow would actually work in nipkgs well, before we make bigger structural calls. (i.e. decide for/against the seperate nix.dev repo)

We welcome any feedback; especially if you’ve contributed docs and can tell from experience where the current process broke down for you. :slight_smile:

3 Likes
11

(nevermind, just realized you addressed this question, sorta. big fan of a separate repo though!)

12

I’m interested to know why the wiki

  1. Won’t be migrated
  2. Is treated as kind of a “lower” documentation, is it just that anyone can edit it?

Do you/does anyone, have an example wiki page that would move to docs?

Overall really excited for this project and to help where/how I can. Big fan of this initiative

3 Likes
13

A wiki is kind of a dumping ground. There’s no narrative or sequence inside of a learning journey.